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Request a catalog or demo CD 

be shipped to you—absolutely FREE!* 
¢ Quality Support! 
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of Knowledge Base articles, FAQs, 
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Chart FX 


FREE Charting for VB.NET 


Software FX is offering a FREE charting solution 
for Windows Forms created with Visual 
Studio.net. Chart FX Lite offers valuable charting 
functionality, including royalty-free distribution; 
2D & 3D line, bar, pie and area charts: gridline & 
axis Manipulation; ability to pass data through 
the API or DataSets; forward code compatibility 
for easy migration to other Chart FX products. 


Software FX 


Any Chart, Anywhere! 


Chart FX Internet 5.5 


The most advanced charting solution for Internet developers. 


Chart FX Internet powerful features: 


e Interactive Image Map Generation 

e Drill-Down Capability 

e Object Oriented API 

e Auto Browser Detection & Response 

e User Interface for Edit and Customization 

e Bit-Streaming Directly to a Browser 
(required for web farms} 

e ActiveX and Netscape Plug-Ins Included 

e Dynamic Template and Code Generation 
(ASP, ColdFusion or Client-Side Code) 

e Included DIC (Visual InterDev 6.0 compliant) 

e Embedded Data Binding 

© Highly Extensible (Annotation, Crosslab, XML) 

© Included Sample Code & KnowledgeBase 

e Included Wireless Extension 

© Scalable Vector Graphics Generation 
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A powerful Technical Analysis charting component 
for financial providers. 
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Some of the financial features are: 


e 4 New Japanese Charts 
50+ Studies available to enhance chart analysis 
Up to 18 user defined indicators, calculated by 
the programmer and displayed as a technical 
or price indicator 
Up to 3 Technical Indicators in a single screen 
12 Custom Interactive Drawing features 
(i.e. Fibonacci Fans, Arcs, etc.} 


Chart FX for .NET 


Rewritten in C# to exist within ee LEE 
.NET as 100% managed code. 


Some of the features are: 
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e Client Server and Internet versions 
« Improved security 
« Easier integration with web services 
e Enhanced XML support | = : 
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« Easily Accessible API 


tool - now embedded! 


_# Any database connectivity 


Get your hands on it! 


Visit www.softwarefx.com or call 
(561) 999-8888 or (800) 392-4278. 


Chart FX Client Server 51] 


Shaping the charting component industry for almost a decade. 


The most feature-rich client server 
architecture charting component available: 


e Convenient Wizard Setup 
e User Interface for Easy Control 


e Active Document Server (OLE Server 

e Dynamic [emplate and Code Generation 
« Integrated Annotation Extension 

e Included Sample Code & KnowledgeBase 
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Some features include: 


« Familiar Chart FX API 
« Works with Embedded Visual Tools 
(eVB and eVC++ 
* Pre-compiled formats MIPS, ARM, SH3/4) 
* ADO CE support 
* Customizable stylus events support 
« Most 2D and 3D Chart FX charts supported 
° Less than 400K Memory footprint 


Chart FX Wireless 
The most complete solution for building mobile applications with 
_Integrated charting capabilities. 


Ine Chant FX [nternetis bundied with the 
AireLogic wireless development kit. 


AireLogic is an IDE that gives a develope! the 
ability to create wireless applications in a 
minimal amount of time without the need of 
intensive programming knowledge. 

° Flowchart-style interface. 


e Built-in debugging 

* just-In-lime Compiler 

« Automatic ASP server and client-side 
code generation and publishing 


AireLogic gives you the most powerful 
development environment and includes 
Chart FX Internet, the most powelul, 
wireless charting capabilities. 
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100+ pages of products 
and information 
for developers! 
Get a FREE subscription 
to our catalog by calling 


800-445-7899 


or subscribe at 
programmersparadise.com 


Paradise Picks 


DevTrack 
by TechExcel 


Powerful Defect Tracking 


DevTrack is the premier defect- and project- 
tracking tool for software development teams, 
helping to ensure that development projects 
finish on time and on budget. DevTrack 
comprehensively tracks and manages all 
defects, change/feature requests, and all 
other development issues. DevTrack also 
provides powerful workflow and process 
automation features, robust searching and 
reporting, and comprehensive point-and- 
click customization. Intuitive and powerful, 
DevTrack provides a scalable out-of-the-box 
solution, at a great value. 
Wwww.programmersparadise.com /techexcel 
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. MKS Toolkit® 


TestTrack” Pro 4 


by Seapine Software” 


Simply Better Bug Tracking 


TestTrack Pro 4 is the industry leading bug 
tracking solution for the Web, Windows, Mac OS 
X, Linux, and Solaris. TestTrack Pro 4 delivers a 
robust feature set: source code control integration, 
with MS VSS, PVCS, CS-RCS, and Perforce, bug 
database access from MS Visual Studio, field 
relationships, XML/ODBC support, customer and 
user test configurations, email notifications, 
email bug importing, duplicate defect handling, 
and more...all backed by top-notch customer 


WWw.programmersparadise.com /seapinesoftware 


Visual SlickEdit® v6.0 
by SlickEdit Inc. 


Now available on FreeBSD! 


Source code analysis, side-by-side file 
comparison, extensive language support, 
easy to implement and configurable to 
your coding styles. New Java capabilities 
including Java Tool Integration for setting 
compile, execute, debug, javadoc and 

jar options. 


Download a 
demo today. 


programmersparadise.com 
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for Developers v8.0 
by MKS Software, Inc. 0 
Build Better Software with Powerful Development 
Tools! Boost your ability to perform cross-platform, 
software development, and Windows scripting 
with MKS Toolkit, the most comprehensive 
solution for Windows® development. This 
powerful NEW RELEASE promises to improve 
productivity, ensure consistency in the 
development process, and save time. 
Also NEW with MKS Toolkit 8.0 is AlertCentre™— 
an add-on solution for monitoring, alerting, 
and process automation. 
WWwW.programmersparadise.com/mks 


Source OffSite Pro Ed. 
by SourceGear Corp. 
Access SourceSafe” over the Internet 


Visual SourceSafe collaboration tool 
for distributed teams. 


e IDE integration 

e Over 10 times faster than RAS 

e Efficient—uses data compression 

e Secure—up to 128-bit data encryption 
e Familiar—the look and feel of VSS 

e Cross-Platform—Windows and UNIX. 


tf Pro edition, 1 user. 
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TX Text Control 9.0 
by The Imaging Source 


TX Text Control Does it All. 


A powerful programming component which allows 
developers to easily add into their application 

sophisticated text formatting and display capabilities 
typically seen only in large word processing programs. 
Download a 
demo today. 
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Diskeeper® 7.0 


by Executive Software 


Maximum system performance — 
Zero Administration. 


NEW RELEASE! DISKEEPER 7.0 
automatic disk defragmenter for 
Windows. “Smart Scheduling™” 

keeps your system at peak performance. 
New breakthrough “PushInstall™” 
allows quick remote installation. 


Tested 300-500% faster and far abe F ae 
more thorough than “built-in” E14 0189 F14 0180 
defragmenters. Buy it now. § 
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VMware Workstation 


by VMware 


VMware Workstation increases the productivity 
of developers and other technical professionals 
by enabling them to run multiple operating 
systems in secure, transportable, high- 
performance virtual computers on physical 
computers. As a result, our customers spend 
more time delivering tangible value to their 
businesses and less time installing operating 
systems, rebooting or reconfiguring hardware. 
VMware Workstation supports standard 
operating systems such as Microsoft Windows 
NT, Windows 2000, Windows XP and Linux. 
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Borland Enterprise Server Web Edition 
by Borland 


Borland® Enterprise Server, Web Edition is a 
complete, scalable, and robust deployment 
platform for Web applications. The Web Edition 
delivers enhanced Borland versions Apache™, 
one of the most popular Web servers, Tomcat, 
the reference implementation Web container, 
and JDataStore™—a database written entirely 
in Java™—for caching, session management, 
and general database needs. Apache and 
Tomcat integration is built on Borland 
VisiBroker,® one of the most widely deployed 
CORBA solutions on the market. 
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¢ 64-bit support 


Scalability 


From embedded 
to the enterprise! 


° Standalone and 
client/server models 

e Small footprint 

* Easy deployment 

¢ Reentrant multi-threading 

¢ Multi-Processor Support 


C-TREE DELIVERS THE 
FLEXIBILITY AND CONTROL YOU 
DEMAND, WHILE KEEPING YOUR 

DEPLOYMENT COSTS LOW 


For over twenty years, FairCom’s proven database technology has been a favorite of 
commercial developers for applications ranging from low level embedded appliances 
to vertical market applications to huge multi-platform, corporate applications. 
FairCom has established this reputation by delivering uncompromising Standalone 
and Client/Server technology in a flexible package that enables you to cut costs while 
utilizing cutting edge technology like our new HUGE file support and 64-bit support. 
FairCom offers this exceptional performance, unsurpassed data availability and rock 
solid reliability with a low total cost of ownership and flexible licensing options. 


Get more for your development dollar! Visit www.faircom.com/ep/freectree today 
for a free developer’s CD. 


FairCom Offices 
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XML and Web services give developers the ability and freedom to cross component, application, 
and organization boundaries regardless of the platform, language, or object model used on 
either side. Our training courses will prepare you to venture into this incredible new area of 


software development. 


Essential XML 


XML has become the common language by 
providing a standard format or data 
exchange. This course will teach you how 
XML layers type and structure over 
information to facilitate interoperability 
between today's distributed systems. You 
will study XML's abstract data model 
(Infoset), the canonical serialization 
format (XML 1.0 + Namespaces), the 
official type system (XML Schemas), and 
also learn how to more effectively 
leverage XML by studying the core APIs 
(SAX/DOM) and other layered technologies 
such as XPath, XSLT, and SOAP. 


Essential Web Services.NET 


Building a Web application that integrates 
heterogeneous operating systems, object 
models, and programming languages 
presents a wide variety of challenges. These 
challenges, however can be easily overcome 
when services are based on open industry 
standards like XML and HTTP. This course 
reveals the concepts behind building open 
"Web" services and present the various 
architectural options offered by the .NET 
API's. In particular, it covers .NET'’s XML 
framework, data access framework, and Its 
various implementations of HTTP. 


Essential ASP.NET 


By carefully considering the features you 
want to use to connect your Web 
applications to Web browsers, you will create 
far superior applications. This course Is 
designed for developers looking to build 
web-based user-interfaces using ASP.NET 
and the .NET runtime. The core issues 
involve building browser-centric web 
applications and provide an in-depth 
exploration of the broad set of new features 
in ASP.NET. These new features include 
server-side and validation controls, Web 
Forms, data access with ADO.NET, Web 
services, and state management. 
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If you need Visual Studio tools for your database front-end application development, choose ComponentOne Studio. 


You'll get: 
e VSFlexGrid® Pro 7.0 ¢ True DBList™ Pro 7.0 ¢ VSSPELL™ 6.0 International Edition 
e True DBGrid® Pro 7.0 e True DBInput™ Pro 6.0 e Three CDs (one for each quarter 
° VSVIEW® 7.0 Reporting Edition e True DataControl™ 6.0 following date of purchase) to include free 
e VSVIEW® 7.0 Classic Edition ¢ ComponentOne Query™ 1.0 updates, upgrades, and new ComponentOne 
¢ ComponentOne WebChart™ 7.0 e SizerOne™ 7.0 ActiveX® releases 
¢ ComponentOne Chart™ 7.0 e VSFORUM™ 2.0 e Free e-mail and online support 


ntroducing ComponentOne Studio’ for .NET 


Premier Subscription Service for Microsoft® .NET™ Framework Developers 


99:%° 
a * Introductory Upgrade Price 


for Current Customers 


95 : 
Introductory Full Price 
for New Customers 


ComponentOne FlexGrid™ for .NET 


lf you're looking for component tools for the Microsoft .NET Framework, you'll want ComponentOne Studio for .NET: 


¢ ComponentOne FlexGrid™ for .NET ¢ Three CDs (one for each quarter following date of purchase) to include 
¢ ComponentOne True DBGrid™ for NET — free updates, upgrades, and new ComponentOne .NET releases 

¢ ComponentOne Reports™ for .NET (new releases on tap include charting, data manipulation, querying, 

¢ ComponentOne Preview™ for .NET and resizing tools) 


ComponentOne Spell™ for .NET e Free e-mail and online support 


Welcome Visual Studio .NET 


This isthe long part of winter. Through the holidays,and | an unusual number of early beta samples to float around. We still 


up until about New Year's Day, winter is portrayed as a wonderful, 
well-lit, flurry-filled wonderland. Rosy-cheeked kids catch snow- 
flakes on their tongues. Skaters enjoy the rink at Rockefeller Cen- 
ter. Clydesdales haul a frosty keg of beer right to your easy chair, 
where youre sitting and watching football. 

The moment the calendar page flips to January 2, however, the 
very nature of winter changes. Suddenly, the charming, horse- 
drawn carriage rides are gone. Whats in their place? Grainy images 
of Buffalo during a snow emergency. Unlucky commuters step- 
ping in sepia-toned puddles of slush. Cars fishtailing and skidding 
into snowdrifts the size of battleships. Steaming cups of lemon- 
flavored cold and flu medication. 

But this winter promises to be different. Visual Studio .NET will 
officially greet the world in February. While this event will mark 
perhaps the most drastic shift in the world of computing in a 
decade, in a way it has a weird feeling of anticlimax. We've been 
covering Visual Studio .NET and the .NET Framework for so long 
now—since September 2000, in fact—that news of the final re- 
lease seems like an incremental step rather than a revolution. But 
February will—come hell or high puddle—bring the real, official 
version of Visual Studio .NET. 

One of the reasons this feels like the third release of Visual 
Studio .NET is because of the rapid evolution of the .NET betas. 
There were significant changes between Beta 1, Beta 2, and the RC 
and release versions of the framework. There's already a bit of 
confusion, since some people are grabbing older code samples and 
finding that they don’t compile. So what's a working geek to do? 

The first, and most important, step is to read up on what changes 
to expect between beta versions of the framework. This is truly an 
unprecedented situation. In most cases, changes between versions 
of a program aren't that big a deal. Maybe a menu item gets turned 
on, or a dialog choice moves around. This is perhaps the first time 
that so many people have used early betas of such a pervasive 
computing platform. A lot of changes were made after seeing how 
people used the .NET Framework in its early days. Certain classes 
were combined or simplified to make the final experience better. 
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have some on our site. We haven't changed the original code or 
articles because our Web site is designed to be an exact archive of 
the print version. But when you look at older pieces, use them for 
their concepts more than for their exact coding hints. Gotdot- 
net.com has documentation about the change between beta ver- 
sions, and MSDN Online will be providing similar information 
once Visual Studio .NET is released. Using that knowledge, along 
with the numerous articles we've provided over the past year and 
half, will be your surest path to .NET Nirvana. 

One of the exciting things in Visual Studio .NET is its language 
agnosticism. If a vendor has written a .NET-compliant language, 
you can use it in Visual Studio .NET. It'll work just as well as C# or 
C++ or Visual Basic. This isn't just a future feature-in-planning. 
There are already nearly two dozen languages being developed for 
Visual Studio .NET: Visual Basic, C#, C++, JScript, APL, Cobol, 
Eiffel, Fortran, Pascal, Perl, Python, RPG, Smalltalk, Oberon, Com- 
ponent Pascal, Haskell/Mondrian, Scheme, Mercury, Alice, and 
even the Java language. 

Of course, years ago we used to cover C programming. When 
MFC was first released, people would complain that they longed 
for the days of pure C articles. While MFC has had a great run, we 
really think that it’s time to check out the framework. MFC’s pur- 
pose was to normalize the oft-confusing Win32 API, to make it 
easier to perform common programming tasks. Its popularity is 
testament to the great job it did in smoothing out some of the 
rougher edges of the underlying programming model. 

We know it's hard to migrate to new technology, even if it’s bet- 
ter. And we're not suggesting that you rush out and rewrite your 
existing projects just to take advantage of .NET. But think of future 
generations. The youth of today are looking up to you. Are you 
going to just abandon their hopes and dreams and cling to an 
outdated programming paradigm? Or are you going to show your 
leadership and stick your toe into the warm waters of the frame- 
work? Its really quite simple when you think of it that way. If you 
still love C++, we have several articles in this issue that will cheer 
you as you tackle Visual Studio .NET. And if you love C, well, you 
can still use a. NET-compatible version of the language! —JT 


keeps profits 
from slipping through 


your hands. 


Meeting this challenge is easy with 
FLEX/m—the de facto standard electronic 
licensing system from GLOBEtrotter. By 
joining the over 2500 software vendors 


shipping over $40 billion of software using 
FLEX/m you'll be able to: 


° Monitor or enforce compliance with 
license terms to reduce unauthorized use. 

e Sell your software with license models 
promoting deeper account penetration 
and greater customer satisfaction. 

¢ Change license terms and business models 
without changing your source code. 

e Electronically deliver licenses 24x7 over 


the world wide web. 


FLEX/m provides you the shortest path 
to flexible electronic licensing and pricing policies that typically increase 


revenues 10 to 20%. 


Don’t wait another day to increase your revenues and profits. 
Contact GLOBEtrotter at 888-755-0861 for more information or visit 


www flexlm.info/msdn/ to download a free IDC report on electronic 


licensing, to demo FLEX/m, or to learn about electronic licensing. 


Now you can capture the profits that have been slipping through your hands. 


ey GLOBE?rotter" 


a ma@rovision company } 


1530 Meridian Avenue, San Jose, CA 95125 
Tel: (408) 445-8100 © Fax: (408) 445-7760 
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Setup Type 
Choose the setup type that best suits your needs. 


~ Power. Flexibility. Intuitive Control. 


Productive. Efficient. Customized. Just words to some. But at InstallShield, it’s the only way 
we know. That's why when we build our new Flagship Product, we do it right. We build 


InstallShield Developer 7. 


InstallShield Developer 7 is the brand new flagship solution from the industry leader in 
software installation and deployment. We've built one product to meet all your needs, 
as this new edition leverages both the power of InstallScriot™ and the benefits of the 

Windows Installer service. This means that when you rely on InstallShield Developer 7, 
you customize your setups using industry-standard script, but can also take advantage 
of built-in support for native Windows Installer features like application auto-repair and 


install-on-demand. InstallShield Developer has it all. 


InstallShield Developer keeps you current and is ready for the future. Today's hot 
installation needs are covered with features like One-Click Install™ Internet installations, 


Source Code Control Integration, and a Visual Dialog Editor—all built right in. 
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AT WWW.INSTALLSHIELD.COM 


The Best Just Got Better! 
InstallShield Developer 7 


© 2002 InstallShield Software Corporation. All rights reserved. InstallShield is a registered trademark and service 
mark of InstallShield Software Corporation. All other trademarks are the property of their respective owners. 


Welcome to the Project Wizard for 
_ Microsoft® Visual C#™ NET 


If your setup needs to be up and running quickly, the Project 
wizard is a great place to start, In just a few minutes you can 
create a Fully Functional setup that performs File transfer, 


creates shortcuts, and provides registry data for your 
application. 


Plus, InstallShield Developer 7 features an easy-to-use visual interface to author 
installations containing both NET and Win32 components. Easily import your Visual 
Basic .NET or Visual C# NET project, scan the project for file dependencies, configure 
NET custom actions, and specify whether a component should be deployed only for 


your application or made available to other applications via the Global Assembly Cache. 


Control all aspects of the NET Assembly Manifest directly using the complete Windows 
Installer 2.0 Table Editor. You can also configure Win32 Assemblies to install Side-by-Side 
Components on Windows XP isolating the application and eliminating conflicts 


associated with shared files. And this is just the beginning! 


With InstallShield Developer 7, you get greater productivity, efficiency, and return on 


investment. And you get to the most important words of all: Complete and Well Done. 


Also known as InstallShield Developer. 


de GET YOUR FULL FEATURED EVALUATION 


InstallShield. 


SOFTWARE CORPORATION 


Resources for Your Developer Toolbox 


THERESA W. CAREY 


RAD Tools for Visual Basic, 
ASP, and SQL 

Lockwood Technical Services Inc. 
has announced the availability of a 
collection of rapid application devel- 
opment tools for developers using 
Visual Basic®, ASP, and SQL. The SQL 
Developer Pack includes Proc- | 
Blaster, Auto-Audit, SQLClean, and 
Auto-Inserts. Proc-Blaster rapidly 
creates SQL stored procedures and 
the Visual Basic, ASP, 
and ADO code to 
process them. 

Auto-Audit automati- | 
cally generates triggers to create a 
SQL Server™ 7.0 audit log and ships 
with a reporting utility. SQLClean 
detects and removes unused stored 
procedures, views, and tables in your 
SQL Server database. Auto-Inserts 
scripts SQL Server data into inserts | 
scripts, allowing data reloads without — 
causing referential integrity errors. 

The VB Developer Pack includes | 
Proc-Blaster (as just described), : 
Query-Blaster, and Auto-Error. Query- 


Blaster creates Access parameter 
queries and the Visual Basic, ASP, 
and ADO code to process them. Auto- 
Error adds error handling and line | 
numbers to your Visual Basic project. 

Lockwood Technical Services Inc. 

8 Medway Branch Road 

Norfolk, MA 02056 

206-723-0887 

http: //www.lockwoodtech.com 


Just the FAQs 

GT Technologies recently 
announced the availability of FAQ 
Factory, an editor and publisher for 
frequently asked questions (FAQ) Web | 
pages. FAQ Factory runs on all | 
desktop versions of Windows® from | 


g . OCKWOODTECH 


Windows 95 through 
Windows XP and 
generates a single output Lz 
file, which can contain en 
Cascade Style Sheet tags, XHTML 
and DHTML and can be placed on any 
platform. FAQ Factory comes with a 
number of different XSL style sheets, 
and you can create others to your 
specifications. FAQ Factory includes 
features such as unlimited topic 
levels, a mini HTML 
, editor, a preview option, 
"@ and site template 
support. The program 

allows you to maintain the UI of your 
Web site by allowing you to insert 
your FAQ into a Web page with a 
single comment tag. 

GT Technologies 

1375 NE Elk Court, #139 

Bend, OR 97701 

541-389-6628 

http: //www.faqfactory.com 


| XML-based Charting 


Active Interface Inc. recently 
announced IntraSight, its interactive 
graphical reporting software for use in 
Web portals and dashboards. 
IntraSight is based on a lightweight 
Activex® or JavaBean component, and 
provides XML-based charting, 
graphics, and data visualization. 
IntraSight is targeted at specialized 
business intelligence, decision 
support, and enterprise 
performance reporting 
applications. Dozens of 
2D and 3D templates are 
available for both 


| traditional business charts and also 


for specialized reporting. IntraSight 
can request data from Active Server 


| Rages that generate XML, or by using 
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the Microsoft XML for 
Analysis SDK or XMLHTTP, 
1 and it can query SQL 

bles and OLAP cubes directly from 

the browser. Update periods can be 

defined for near-real-time reporting of 

continuously changing data sources 

- pertaining to business or IT pro- 
cesses. IntraSight requires Microsoft 
Internet Explorer 5.x browsers and 
integrates with Microsoft SharePoint” 

~ and SQL Server 2000. 

| Active Interface Inc. 

| P.O. Box 38475 

| Pittsburgh, PA 15238 

| 412-901-1184 

http: //www.intrasight.com 


Code Generation Engine 

Palmersoft has released The 
Palmersoft Generator, a power tool 
that uses a template-driven approach 
designed to provide overall control 
| over type and style to programmers. 
With the Palmersoft Generator, users 
-.can create reusable Data Definitions 
to drive the code generation process. 
Data Definitions are lists of field 
attributes that the user can employ 
inside an application. 

The Palmersoft Generator 
combines Data Definitions with 
Models to produce code that is 
tailored to your specific needs. Data 
Definitions allow you to implement 
the same database functionality 
across several platforms, 
simultaneously 
generating source code © 
for Visual Basic, SQL, 
| C++, and HTML. 
| Alternatively, with numerous modules 
_ in a Visual Basic project that refer to 


- the same data, the Palmersoft 
' Generator can author code for each of 
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Choice for Text Retrieval® since 1991 


“Superb ... a multitude of high-end 
features” — PC Magazine 


“A powerful text mining engine ... 
ctive because of the level of 
intelligence it displays” — PC Al 


“Wery powerful ... a staggering 
number of ways to search” 
— Windows Magazine 


“impressive” — PC Ma azine Online 


Search the many 
forms of data that 
exist across a large 
enterprise network 
* from $800 


Add power 

searching to 

a product 

* extensive 
Ss sample source 
Publish a searchable code in multiple 
database to CD, DVD programming 
* from $2,500 languages 

* from $999 


p by 
searching to your y.dtsearch.com 
site * $999 per se y 


Fast, precisi 
* over two dc 


database, sp 


* FindPlus® d 


* point and click 
Hit highlig 
¢ highlights h 
keeping em ed links and images intact 
* converts other file types to HTML for display 
with highlighted hits 


1-800-IT-FINDS 
www.dtsearch.com 


sales@dtsearch.com 


_ can be used to insert the names of 
_ Variables from your database, 


| Driver Development Tools 
| / Kerne!Driver / Hardware 


- Swap software (GO-HotSwap) is now 
_ available from Jungo Software | 
_ Technologies Inc. The new release of 
| these driver development tools 


_ Windows XP (RC1), and WinDriver 

| Support for Windows CE 3.0. Based 
| on Jungo’s cross-platform technology, | 
_ drivers developed using WinDriver or 


| versions) may be ported to the newly 
| Supported operating systems without | 
_ additional code modification. 


_ toolkit for creating monolithic device | 
| drivers for custom hardware. It | 


environment, APIs, diagnostic and : 
_ debug utilities and samples, which : 
| enable development of drivers under | 
_ all versions of Windows from 
_ Windows 95 through Windows XP. | Enterprise Modeling Software 
_ WinDriver supports USB/PCI/ | 
| CompactPCl/ISA/ISAPnP and EISA _ System Architect V8.5. The product 


| development toolkit that enables the 
| creation of kernel-mode drivers, | 
| especially Layered (Filter and _ down to the IT systems level for 


_ Standard drivers, 


| them by combining different Models _|_ ging, driver code generation, and 
| with the same Data Definition. _ driver debugging. Kernel!Driver 


PalmerSoft Generator Models | supports USB/PCI/CompactPCl/ISA/ 


| contain code in the language of your | ISAPnP and EISA hardware. Kernel- 
| choice combined with intelligent 


Driver is a set of C++ classes that 
keywords. During generation, the | encapsulate long and complicated 
Models control what is generated and | DDK tasks on Windows NT and 

how that code is formatted. Keywords | Windows 2000. Hardware Debugger 
allows detection of USB/PCI/ 

| CompactPCI/ISA/ISAPnP/EISA 

_ hardware and its resources, without 


intelligently enclose code, loop 


| through the different types of fields in | having to develop a driver. Hardware 
_ atable, and create legal variable 


Debugger enables engineers to 
names from field names. diagnose and verify untested hard- 
PalmerSoft | ware under all desktop versions of 
10601 Tierrasanta Boulevard, #245 Windows since Windows 95. Hara- 
San Diego, CA 92124 ware Debugger for PCI enables 
Eee HN veel Mens oTee ath | accessing memory and I/O ranges, 
| listening to interrupts and 
defining and accessing 
registers. Hardware | 
| Debugger for USB allows 
- monitoring and transferring of data 
| through pipes. 


Version 5.03 of WinDriver 


Debugger, and CompactPCI Hot 


__GO-HotSwap is a PICMG-compliant, 
cross-platform, Full Hot Swap 
software infrastructure for Windows 
95, Windows 98, Windows NT®, and 
Windows 2000. It plugs into the 
operating system and adds all the 
necessary software modules required 
to support CompactPCl! Hot Swap, 
such as Hot Swap events detection, 
dynamic resource allocation (while 
the system is running), PCI registers 
initialization, reenumeration and 
automatic initiation of software 
connection/disconnection processes. 

Jungo Software Technologies 

6 Hagavish Street 

P.O. Box 8493 

Netanya, 42504, Israel 

877-514-0537, +972-9-885-8611 

http://www.jungo.com 


includes WinDriver, KernelDriver and 
Hardware Debugger support for 


KernelDriver (current or previous 


WinDriver is a driver development 


includes a graphical development 


Popkin Software has released 


hardware. 
Kerne!Driver is a driver 


integrates business goals and 
processes, objects, components and 
data into a single conceptual 
framework that distills information 


shared 
development. 
Features include 
UML 1.4 


Miniport) and 


providing tools for 
hardware debug- 


has been upgraded to allow complete 
compatibility with Visual Basic. SQL 
Tools Version 2 gives developers a 
System Architect V8.5 enables way to access databases using Visual 
businesses to develop a blueprint for Basic. The product is compatible with 


compatibility, XML integration, | 
an organization’s information | more than 50 databases, including 


database-model synchronization, and 
a cross-reference editor. 


structure. A common, multi-user Microsoft Access, SQL Server, 
repository offers team collaboration, Oracle, Excel spreadsheets, dBase, 
centralized information management, and MySQL. 
and data reuse. System Architect SQL Tools Version 2 allows 
V8.5 supports design, development, developers to access SQL-compatible 
testing, and databases using Visual 
deployment of an Basic with functions 
enterprise-wide such as SQL_Open- 
architectural frame- Database, SQL_State- 
work for the full ment, and SQL_ 
development lifecycle, | — FetchResult, avoiding 
regardless of the methodology or | the complexities of ADO, DAO, RDO, 
the language. _ and OLE DB. SQL Tools works with 
The product includes an XML | any version of MDAC, including the 
modeling module, designed to : versions that are preinstalled on 
facilitate sharing and reuse of XML | Windows 98 SE, Windows Me, 
components and schema standards — Windows NT 4.0, Windows 2000, and 
for a deployed architecture. System : Windows XP. It is not usually 
Architect also supports UML 1.4 | necessary to distribute database 
extensibility mechanisms with user- _ drivers with a Visual Basic-based 
defined images including Web | orogram when you use SQL Tools. 
Application Extensions (WAE). | SQL Tools is available in two 
The DB Synchronize feature can | versions. SQL Tools Standard Version 
identify and help correct discrepan- | 2.00 provides all of the basic 
cies between a model and database — database functions that most small 
to keep developers and database | to medium projects will require. 
administrators in sync, and supports : SQL Tools Pro Version 2.00 adds a 
SQL Server 7.0. The cross-reference _ wide range of features for medium to 
matrix editor allows users to add, | large projects. 
cross-reference, and update | Perfect Sync Software 


definitions across the repository. A ciaacoy Wate a8 / B 
multi-user repository enhances 
consistency ae ee across ae OO 

: http: //www.perfectsync.com 
workgroup development, allowing 
users to interact. 

System Architect supports various 
languages and databases, offers 
reporting and documenting systems, 
and provides HTML generation for 
model publishing over an Internet/ 


extranet. 
Popkin Software 
11 Park Place 
New York, NY 10007 
800-732-5227, 212-571-3434 
http://www. popkin.com 


Change URLs on the Fly 

Qwerksoft recently announced the 
availability of ISRewrite 1.2, a URL 
rewriting filter for Microsoft Internet 
Information Services (IIS) that allows 
requested URLs to be changed on the 
fly. This ISAPI filter offers Web- 
masters greater control over the URL | 
as seen by the client. With II[SRewrite, 
URLs that look static to a browser can 


actually be rewritten dynamically by 
the server (such as /catalog/128/ 


SQL Tools with Visual Basic 

Perfect Sync Software has 
announced the release of Version 
2.00 of its SQL Tools package, which 


& 


Expand your Visual Basic 
and Visual C++ Development 
with Measurement Studio” 
Productivity enhancing tools, 


including C++ classes and 
ActiveX controls: 


e (Measurement hardware 
interfaces 


g 


User interface components 


2 


Live data sharing 


8 


Distributed measurements 


Signal analysis 


index.htm to /catalog.asp?id=128). 
Static URLs allow greater portions of 
dynamically generated sites to be 
indexed by search engines and 
increases Web site visibility on 
the Internet. 

liSRewrite has a 
flexible URL rewriting 
engine based on regular 
expressions. URLs that 
match a regular expression can be 
rewritten into another URL, redirected 
to another location, or forbidden 
entirely. It can also rewrite URLS 
based on variables (Such as the User 
Agent or the Server Port) and has 


logging capabilities. IISRewrite can be | 


used to catch IIS vulnerabilities for 
logging and reporting, protect Web 
sites from “deep linking” of images 
and files, and is able to rewrite 
download links to work around 
browser bugs. 

Qwerksoft 

1648 Willow Drive 

Kaysville, UT 84037 

888-282-5887 

http: //www.qwerksoft.com 


_ the workflow, access control, and 

_ history of each bug during its 

_ lifecycle. It runs on Windows 95, 

_ Windows 98, Windows NT, Windows 
_ 2000, and Windows XP. 


| elQ LogAnalyzer 2.0 and elQ ! 
_ Professional Suite 2.0, which |MICRO 
_ include features such as FTP 
_ server analysis, proxy server 
_ analysis, streaming media analysis, 


Developers can investigate and 


_ resolve problems that are 

_ categorized, prioritized, and sorted to 
_ their specific needs. Testers can 

| generate bug reports and verify 


corrected problems 
while evaluating the 
efficiency of bug 

- detection methods. 
QuickBugs maintains 


Excel Software 

19 Misty Mesa Court 

Placitas, NM 87043 
505-771-3719 

http: //www.excelsoftware.com 


elQnetworks Inc. has introduced 


_ monitoring, and alerting. elQ Analytics | 


Catch and Kill Bugs 

Excel Software is shipping 
QuickBugs, a tool for reporting, 
tracking, and resolving the bugs, 
issues, changes, and new features 
involved in product development. Key 
attributes include a shared repository 
accessible to multiple users, multiple 
projects with assigned 
responsibilities, and 
configurable access and 
privileges for users on 
each project. Most 
features in QuickBugs are 
configurable to the organization and 
specific user needs including data 
collection fields, workflow, views, 
queries, reports, security, and access 
control. QuickBugs is a single exe 
that implements cooperative clients 
of a shared repository of XML-based 
data. Given its XML-based foundation, 
all bugs, views, queries, reports, and 
configuration data are completely 
accessible to third-party tools. 


_ Series 2.0 solutions provide Web- 

_ analysis data such as what content 

_ visitors are looking at, which paths 

_ they are following to reach key 

_ information, what sites they're 

- coming from, which external sites 

_ intranet users are visiting, and which 
_ streaming media clips are most 


( ar | 
Alimama, 


elQnetworks 


_ performance by analyzing visitor 


popular. 

elQ LogAnalyzer is the 
entry-level Web and FTP 
log analysis and reporting 
solution for businesses 
looking to improve site 


behavior and site activity. 
Targeted for single-server Web 
sites, LogAnalyzer produces up to 80 


_ essential reports on Web and FTP site — 
| visitor patterns, site usage, referring | 
_ sites, visitor paths, demographics, 

_ and more. The built-in scheduler 

_ allows for automated delivery of 

_ reports in many formats to multiple 

_ users within an enterprise. 


elQ Professional Suite is targeted 
at small and medium-sized 
_ businesses operating multiple Web or 
_ FTP servers, offering Web and FIP log 
| analysis, proxy server analysis, 
_ streaming media analysis, 
_ monitoring, and alerting features. 
'  elQnetworks Inc. 
2 Old Weston Road 
Wayland, MA 01778 
508-358-7601 
http: //www.eiqnetworks.com 


Build Thin Client Applications 
MicroOLAP Technologies has 


_ announced the release of MySQL 

| Direct Access Components 

_ (MySQLDAC), a library of native VCL 
_ components for direct access to 

_ MySQL database server. MySQL 

| Direct Access Components provides 


| Web Site Performance Analysis | direct access to MySQL server from 


Borland Delphi/C++Builder 
applications, without 
requiring BDE/ODBC on the 
client side. It supports all 


| MySQL-specific features (Show, 
| Transaction, Ping, Kill Process, Check 


and Repair Table, and more) and 
simplifies client/server application 


_ development. Features include Insert, 
| Update, Delete and Refresh, support 
_ of BLOB fields, and the ability to 

_ speed up record fetch from the 

_ database. The library also includes 

_ the TDBImageEx component for JPEG 

_ images. The interface of MySQLDAC 

_ is BDE-compatible, so this component 
_ set allows migration of existing 

| projects from the BDE/ODBC scheme 
_ to the native one. MySQLDAC 

_ supports MySQL 3.23.xxstable 

| versions for all existing platforms. 


microOLAP Technologies LLC 
208 West State Street 
Trenton, NJ 08608 

http: //www.microolap.com 


| Send your New Stuff to Theresa at 


newstuff@microsoft.com. 


| Her byline has appeared in Barron’s and PC World. 
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| Threading in MSXML, Sorting XML, Order-by, Changing Mouse Pointer, and More 
NANCY MICHELL 


Q The MSXML 4.0 SDK documents say that Msxml2. DOMDocu- 
ment.4.0 is apartment threaded and Msxml2.FreeThreadedDOM- 
Document.4.0 is freethreaded. But after I installed the 4.0 package 
and examined the register, the Msxml2. D0MDocument.4.0 is 
also marked as “Both” threading models. Can you tell me if the 
documentation is wrong? 


A Sort of. DOMDocument is not really as limited as “apartment 
threaded” implies. It will work without problems on any thread, as 


long as it is never used simultaneously on multiple threads. This - 


includes calling AddRef/Release. The FreeThreadDOMDocument 
adds API-level locking to support safe multithreaded access, as 
well as thread-safe AddRef/Release. The client of DOMDocu- 
ment.4.0 is responsible for making sure that simultaneous use by 
multiple threads won't happen. Delegating the responsibility for 
maintaining thread safety to COM/OLE slows large document 
DOM tree walks by a factor of roughly 1000. 


Q I was querying SQL with ADO persisted as XML, and I got the 
following schema for a field: 


<s:AttributeType name='CaseldleDays' rs:number="5" rs:nullable='true'> 
<s:datatype dt:type="float’ dt:maxLength='8" rs:precision='15' 
rs:fixedlength='true'/> 
</s:AttributeType> 


However, when I used XSL for transformation (xmlns:xsl="http:/ | 


/www.w3.org/TR/WD-xs!”), the order-by attribute in a for-each 
element sorted the field like strings, instead of like numbers. Am I 
missing something? 


A Try using the following code, replacing @CaseldleDays with 
whatever field you are trying to sort on: 

<xsl:for-each select="whatever” order-by=number (@CaseldleDays)> 

Though I'd recommend moving to the XSLT implementation in 
MSXML 3.0, in which case you can use <xsl:sort data- 


type“number”>, I would also recommend using the built-in XML | 
features of SQL Server™ 2000 (use SQLXML Web Release 2, down- | 
loadable at http://msdn.microsoft.com/downloads/sample.asp?url=/MSDN-FILES/ 
027/001/602/msdncompositedoc.xml, if youre still using SQL Server 7.0). 


SQLXML provides faster XML serialization than ADO recordsets 
and allows you to easily sort your data directly in the database 
without requiring XSL post-processing. 

With SQLXML, you can do either client-side or server-side 
transformations, or both. Sorting data on the server allows you to 


stream the XML results very efficiently to the client. On the other 
hand, if you know that your server is already too busy completing 
other tasks and you have to offload computation to the client, then 
sorting on the client is the answer. 


Q | am trying to use an xsl:for-each statement to process XML 
nodes in reverse document order. I’ve tried various order-by clauses, 
but this seems to be limited to ordering by the value of the node 
while I want to order by the childnumber of the node. 

So, for this XML: 


<foo> 
<a>3</a> 
<a>1</a> 
<a>4</a> 

</f00> 


<xsl:for-each select=“foo/ 
a’> processes the nodes 
like so: 


3 
1 
4 


But, I want the nodes to be 
processed like this: 


4 
1 
3 


A, One solution is to use the number function in the old namespace 
(http://www.w3.org/TR/WD-xsl), like so: 


order-by="- number(a)" 


But please note this solution works only with the old namespace: 


<?xml version='1.0'?> 
<xsl:stylesheet xmilns:xsl="http://www.w3.org/TR/WD-xs1"> 
<xsl:template match="/"> 
<xsl:for-each select="foo/a" order-by="- 
<a><xsl:value-of select="."/></a> 
</xs1:for-each> 
</xsl:template> 
</xsl:stylesheet> 


number(a)"> 


The number function has different meanings in the old namespace 
and the new one. Using the new namespace you can write 

<xsl:sort select="-position()" data-type="number"/> 
inside your <xsl:for-each> element. And by the way, if no data 
type is specified, the expression will default to a data-type of “text.” 


@ How do I change the mouse pointer shape in VBScript? After 
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clicking the button, I want to change the pointer to an hourglass 
(busy). The problem is that I have an ASP.NET button (which 
executes on the server side) and I want to change the mouse pointer 
on the onclick event of that button. 


Figure 1 Changing the Cursor 


A Here’s an example (not ASP.NET-specific) that may help (see 
Figure 1). The code to change the cursor is encapsulated in the 
function SetWait. You can call the function using the onclick 
method of the button. This simple example shows how to change 
the button text to“Cancel” and not have the cursor be an hourglass 
when over the button, but you can adapt it to your specific needs. 


document ? 
Por example, consider the following snippet : 


<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmins:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<soap:Body> 
<Result xmlns="urn:acme-org:results"> 
~: <Job> 
<contacts> 
<contact>J Doe</contact> 
<contact>J Q Public</contact> 
</contacts> 


AYou may want to generate absolute XPath to a particular element 


oy node. This can be done easily with the following XSLT fragment: 


I'd like to know the absolute path of the second “contact” node: 
/soap:Envelope/soap:Body[1]/Result/Job/contacts/contact[2] 


<xsl:for-each select="ancestor- or-self::*">/<xsl:value-of 


~ Q Is there any way to obtain the absolute XPath of a node within a : 
! select="name()"/></xs1:for-each> 


If a malloc call takes 200 psec on a single-CPU box, 
how long will it take on a quad-processor box? 
Answer: up to 200 times longer! 


(based on average time for malloc calls in a test program with 50 threads on Windows 2000.) 


SmartHeap/SMP 


Solaris CRT 


Heap operations/second 


1 CPU 2 CPUs 4 CPUs 8 CPUs 


Compiler heap implementations allow only one thread at a time to be active in the heap. This architecture, while thread-safe, is not 
thread optimized. If multiple threads are running, all but one will be blocked by the heap manager, nullifying the benefit of multiple 
CPUs. Worse yet, each time a thread is blocked, the OS invokes a context switch. The result: adding processors results in a vicious 
cycle of context switching that prevents your app from scaling and can actually make it run much slower as more CPUs are added. 


Find out how firms like Netscape, Sun, Palm, IBM, Lucent, HP, Veritas, MicroStrategy, NASDAQ, i2, BMC, Bloomberg, Computer 
Associates, NEON, Cognos, Autodesk, DoubleClick, Teradyne, E.piphany, Allaire, OpenWave, Fidelity, Merrill Lynch, Deutsche Bank, 
Barclays, Ericsson, UPS, and others are achieving 100%-1000% performance improvement. 


| www.microquill.com 


The resulting XPath expression will contain node names like 
/A/B/C, but what if element B has more than one C element as its 
child? You can add a position predicate to the expression: 


<xsl:for-each select="ancestor-or-self::*">/<xsl:value-of 
select="name()"/>[<xsl:number />]</xs1:for-each> 


Now the expression can look like /A[1]/B[1]/C[2], for example. 
You can go further and generate position predicates only if it is 
needed (there is more than one node with this name): 


<xsl:for-each select="ancestor-or-self::*"> 
<xs]:text>/</xs1:text><xsl:value-of select="name()"/> 
<xsl:if test="count(parent: :node()/*[local-name() = local- 
name(current()) and namespace-uri() = 
namespace-uri(current())]) != 1">[<xsl:number />]</xsl:if> 
</xs1:for-each> 


It’s also possible to extend this code to generate templates for 
attributes and text nodes as well. Templates that do the trick are 
included in this month’s download (see http://msdn.microsoft.com/ 
msdnmag/code02.asp). : 

Please note that there are some limitations of this technology. If 
the element has a non-null default namespace you will generate it 
with an empty prefix in the XPath expression and it will never be 
matched. For example, <A><B xmlns=“Foo” /><A/> generates 
A/B. That is not correct. 


Q Iam developing a Web-based application that uses the MSXML 
Parser 3.0 SP2 (http://msdn.microsoft.com/downloads/sample.asp?url=/MSDN- 
FILES/027/001/772/msdncompositedoc.xml) on the server and the client 
(with JScript’ client code). I need to know exactly which version of 
MSXML is installed on the client so it can ask for an upgrade. Is 
there a way to identify the version on the client with JScript code or 
a Visual Basic’-based app? For security reasons, the client is not 
able to read the registry. 


A This can be done on the client with JScript by using nested try/ 
catch blocks. Start out with a null object reference. Then try to load 
the most recent version of MSXML using the version-dependent 
PROGID. If that fails, start another try/catch block and try to load 
the next most recent version of MSXML. Keep repeating this pro- 
cess until you finally get back a valid object, at which point you 
should know exactly which version of MSXML is installed on the 
client machine in question. 

A simple function to test whether MSXML 3.0 is installed is 
shown in Figure 2. You could extend this by adding additional tests 
inside the nested catch blocks. 

Figure 3 shows an extended XML version detector in action. 
Figure 4 lists the code. 


Q Ihave the following XML: 


<testmodule> 
<testcases filter="Somefilter"> 
<testcase> 
<variations> 
<variation filter="bvt"> 


</variation> 
</variations> 
</testcase> 
</testcases> 
</testmodule> a 


Figure 2 MSXML Detect 


The filter attribute, which currently sits on the variation node, 
can also be present on any other level (testmodule, testcase, varia- 


tions, and so on). I am looking for an XPath query which, when 


executed at the lowermost variation node, would give me the near- 
est/lowest-level filter attribute value in the tree. In this case I should 
get “bvt.” In the following case I should get “labrun, not “extended.” 


<testmodule filter="extended"> 
<testcases> 
<testcase filter="labrun"> 
<variations> 
<variation> 


</variation> 
</variations> 
</testcase> 
</testcases> 
</testmodul e> 


A This query returns the value of the filter attribute of the current 
node or one of its parents, whichever is closer. 
<xsl:value-of select="ancestor-or-self::*[@filter][1]/@filter"/> 


Q To be certain that our users can find information on our site, we 


Microsoft Inte ret Explorer: 


. Edit View Favarites Tools Help 


'XML Client Version 
Detector 


| Click the "Detect XML Version" button below to get information, 
| about the major XML version installed on this client. 
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Extended MSXML Detect 


want to have two navigation methods leading to the same places. _ learn that it’s just a different link to the same place, which is gener- 
Whats the best way to accomplish this? ally very frustrating for users. | 


A It’s best not to do this at all. Your goal should be speed and — 
accuracy, and if you offer more than one choice, youre going to : j ; 

| aay ' ilecach if fecal | Derek Denny-Brown, Daniel Cheung, Arpan Desai, Sergey Dubinets, Pranav Kandula, Anton 
Cae MES RGR Cong! at subUle ditterences there may be be- | anounov, Dean Pachosa, Ken Stanfield, Karthik Veeraswamy, Suveen Kumar Reddy Vuppala, 
tween the choices. It actually takes several attempts for them to | Barry Webberley, Guang-an Wu, Feng Yue, and Meiji Yugawa. 


: Got a question? Send questions and comments to webqa@microsoft.com. 


Thanks to the following Microsoft developers for their technical expertise: Tiziano Bergonzi, 
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e testing prior to delivery. | , 
= Platform Dependency Analysis - Ensure the cross-platform 
compatibility of your applications, from use of COM Callable 
Wrappers to platform specific API calls. 
= Integrated Data Analysis - With the metrics provided with our 
profilers, you can get to work and eliminate unsafe code via our 
easy to use interface, without guesswork or hassles. 


And so much more... 


TestComplete - MailE ditor 


= Unrivaled Support for Functional, Unit, and Regression Testing 
for both Windows and Web based applications. : 
= Full Language Independence; all test scripts can be recorded 
visually or written using a language of choice (VBScript, JScript, 
C++, DelphiScript). 
= Beyond Black Box Testing with IDE like capabilities. 
si _. = Object Browser which displays all available Properties and 
Methods of each selected object. 
ea Gh zea ios snl gid = Build Automated Self-Testing Applications; so your projects test 
ae And so much more... 
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Got Bottlenecks? Want to bapreve Performance of 
Your MET Apps? 


° a 


with a 60 day, no questions asked money-bac! 
you've ever used, you can return them for an im 


AutomatedQA Corp 
www.AutomatedQA.com 
(702) 891-9424 


Internet industries. Whether your project requires 
support, (or all of the above!) LEADTOOLS is your 
m multiple vendors when you can get all of your 


ActiveX - COM - API - G++ Class Library 
DICAL IMAGING 


fA 3.0 - Supports the latest specifications, 
g all standard IOD classes and modalities (CR, 
M, US, RF, SC, VL, Worklist, etc.) and DICOM 


communications protocol - COMPLETE 
including all Service Classes (Verification, 
Query/Retrieve, Patient Management, etc). 
communications functions to simplify the 
DICOM client/server applications. 

| image processing - The richest in the 
pporting 1,2,3,4,5,6,7,8,12,16,24,32,48 
ages. Includes 8-16 bit grayscale display 
veling and LUT support. 

icludes Medical specific measuring and 
ions like cross product, ruler, 


curve, polygon, 
1, polydraw, and 
I ypy or move objects 
between ee lock ingivicue| ers. Add, edit, 
delete, rotate, translate and scale objects and layers. 
| Convert points from world spa screen space and 
Ree Specialized vice versa. Pixel accurate hi 

lack and ScaleToGray, Also includes 3-D viewin , shadow, camera), 3 
vector engines (GDI, OpenGL and DirectX), convert or 
overlay vector drawings to any LEAD supported raster 
format. 


standard ScanSoft SDK 5.0 Pro engine, includes preset MULTIMEDIA IMAGING 


confidence and accuracy levels, artificial intelligence, 
defir the Play, Edit and Save - Comprehensive support of 


multimedia formats including AVI, ASF, WMV, WMA, 
MP3, WAV, MIDI, SND, AIF, AIFC, MPEG-1, MPEG-2 files. 


Capture - Capture multimedia data from any 


INTERNET IMAGING DirectShow (WDM) Windows driver. 


Support for client server development over the video Codecs - MJPEG, MCMP and Wavelet. 
Internet or LAN - Provides a framework for sending 


/receiving commands from one computer to another. 


Control Image processing remotely - Allows for 


creation of "remote control" type applications where 
image processing can take place onaremote computer. |. LEADTOOLS toolkits ship with sample source code for 


Small COM objects and ActiveX controls - Internet Visual Basic, Visual CaF Visual C#, Visual Basic NEW, 
enable LEADTOOLS Raster imaging functionality but C/C++, C++ Builder, Visual J++, Delphi, and VB and 
greatly reduce redistribution requirements. ; Java script. And support for Visual Studio 6.0 database 


New HTTP and FTP functionality - Provides connectivity (Oracle, SQL, OLE DB, ODBC, and JET) 
programmatic control of FTP & HTTP servers. 


Upload Control - For sending files to an HTTP server. NEW VERSION 13} 


Digital Paint | www.leadtools.com 


Extensive high-level and low-level options 
available for brush, shape, region, fill and text. sales@leadtools.com or call: 800-637-4699 


VisCINOLOGIES 


1201 Greenwood Cliff, Suite 400 Charlotte, NC 28204 
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DirectShow Filters - Rotate, resize (bicubic and 
resample), brightness, contrast and more. 


=AD and LEADTOOLS are registered trademarks of LEAD Technologies, Inc. ISIS@® is a registered trademark of Pixel Translations, a division of Input Software, Inc. All other product names are trademarks of their respective owners. 


Publishing and Discovering Web Services with DISCO and UDDI 
AARON SKONNARD 


nce a Web Service has been deployed, potential users must be 
able to discover where it is and how it works. DISCO is a 
Microsoft" technology for publishing and discovering Web Ser- 
vices. Universal Description, Discovery, and Integration (UDDI) 
is an industry-wide initiative that defines a SOAP-based protocol 
for updating and querying Web Service information repositories. 
Like DISCO, UDDI makes it possible to publish and discover a 
Web Service, maximizing the site’s reach and ultimate success. This 
column will introduce you to both of these technologies and dis- 
cuss their strengths and weaknesses. 


0 


Introduction to Web Service Technologies 

Web Services are all the rage these days, especially now that 
there is such extensive support for them in the Microsoft .NET 
Framework. Using .NET technologies, developers can implement 
Web Services through ASP.NET projects (.asmx) or through more 
direct, hands-on IHttpHandler implementations (.ashx). Both ap- 
proaches provide the necessary infrastructure for sending and re- 
ceiving XML-based messages over HTTP, which is the protocol at 
the heart of Web Services. 

A Web Service is an application designed for machine consump- 
tion, typically built using XML with HTTP as the transport proto- 
col because of its widespread availability. XML is used because of 
its flexible cross-platform support and its ability to add type and 
structure to the message payloads. 

XML 1.0 defines the universally supported transfer syntax and 
XML Schema defines XMULs type system. Together these tech- 
nologies make it possible to map between application type sys- 
tems such as those for the .NET Common Language Runtime 
(CLR) or the Java Virtual Machine (JVM) and XML, with ma- 
chines doing all of the processing. Invoking a Web Service is 
achieved by simply sending an XML document to a designated 
URL endpoint. The Web Service typically responds by sending 
another XML document back to the client. The combination of a 
request and response message is typically referred to as a Web 
Service operation. 

Since Web Service operations are machine consumable, it would 
make sense if their descriptions (or metadata) were also machine 
consumable. In other words, a machine should be able to query a 
particular endpoint and discover what services are available and 
determine how they work. 


The Web Service Description Language (WSDL) is an ongoing | 


initiative that’s attempting to standardize how Web Services can be 
described in XML format. Microsoft .NET Beta 2 supports the 
current WSDL draft for this purpose. A WSDL document describes 
a service's operations in terms of messages and (typically) XML 
Schema type definitions, as well as how they are bound to various 
protocols and endpoints. 

Once a client can get its hands on a WSDL document, it should 
have enough information to know how to interact with the ae 
Web Service. But how does 
the client get its hands ona 
WSDL document? If the 
client knows where the 
WSDL document resides, 
it can simply ask for it via 
HTTP. However, if the 
client doesn't know where 
the WSDL lives, a discov- 
ery mechanism is needed. 

DISCO, introduced in 
.NET, makes it possible for clients to reflect against endpoints to 
discover services and their associated WSDL documents. DISCO 
is supported in the current betas through several helpful tools. 

On a larger scale, the standards organizations have been work- 
ing on the UDDI discovery protocol (see http://www.UDDI.org). UDDI 
defines an API for interacting with a centralized Web Service in- 
formation repository. Developers can register their services with a 
UDDI site, and other developers can query the site to find info. In 
order to support richer, more specific lookups, a UDDI site holds 
much more information than simply the WSDL document. 


Deploying Web Services 

Deployment is the process of copying all of the service's re- 
quired files to the production machines where it will reside. De- 
ployment of an Internet Information Services (IIS)-based Web 
Service requires that you create a virtual root (vroot) on the pro- 
duction Web server running IIS and copy the .asmx/.ashx files and 
other configuration files into that vroot.A \bin subdirectory within 
the new vroot houses all of the assembly dependencies. 

To configure a Web Service, create a web.config file for the par- 
ticular service and place it in the vroot along with the other files. A 


| web.config file makes it possible to override the vroots default 


configuration settings with respect to compilation, security, glo- 
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Figure 1 resuits.discomap 


balization,and HTTP handler mappings. The directory of a simple 
Web Service that resides in the math vroot would be structured 
like the following directory: 


\wwwroot 
\math (vroot) 
math. asmx 
web.config 
\bin 
simpleMath.d1l 
complexMath.d11 


Discovery with DISCO 


In the past, most consumers found out about new Web Services 
(and their endpoint addresses) by browsing the Web, receiving an 
e-mail, or by word-of-mouth. Now, DISCO can define a docu- 
ment format along with an interrogation algorithm, making it pos- 
sible to discover the Web Services exposed ona given server. DISCO 


also makes it possible to discover the capabilities of each Web 


Service (via documentation) and how to interact with it (via 
WSDL). To publish a deployed Web Service using DISCO, you 
simply need to create a .disco file and place it in the vroot along 
with the other service-related configuration files, like so: 
\inetpub 
\wwwroot 
\math (vroot) 
math. asmx 
web.config 
math.disco 
\bin 
simpleMath.d11 
complexMath.d11 
The .disco document is 
an XML document that sim- 
ply contains links to other re- 
_ sources that describe the Web 
Service, much like an HTML 
file that contains human- 
readable documentation or. 
a WSDL file containing the 
interface contract. The fol- 
lowing is a DISCO document 
skeleton that will serve as a 
starting point. 


<fdiscavery> 


The XML Files 


Figure 2 Adding a Web Reference 


<disco:discovery 
xmlns:disco="http://schemas.xmlsoap.org/disco/"> 
<!-- references go here --> 

</disco:discovery> | 


Notice that the root element has the name discovery from the 
http://schemas.xmlsoap.org/disco/ namespace. The references to 
other resources are placed within the discovery element: 


<disco:discovery 
xmlns:disco="http://schemas.xmlsoap.org/disco/" 
xmlns:scl="http://schemas.xmlsoap.org/disco/scl/"> 
<!-- reference to other DISCO document --> 
<disco:discoveryRef 
ref="related-services/default.disco"/> 
<!-- reference to WSDL and documentation --> 
<scl:contractRef ref="math.asmx?wsd1" 
docRef="math.asmx"/> 
</disco:discovery> 


The main element is contractRef, which belongs to a different 
namespace than the rest of the DISCO-related elements. contract- 
Ref has two attributes, ref and docRef, which point to the WSDL 
and documentation files for a given Web Service. 

The discoveryRef element lets you link the given DISCO docu- 
ment to other DISCO documents. This linking allows you to cre- 
ate a Web of related DISCO documents spanning multiple 
machines and even multiple organizations. This is especially use- 
ful if the DISCO client utility provides a mechanism to traverse the 
links. These are the only elements that you have to be concerned 
about in the DISCO namespace. 


DISCO Client Utilities 


There are currently two tools available for discovering the DISCO 
document once it’s in place. One is a command-line client called 
disco.exe; the other is the Add Web Reference feature in Visual 
Studio® .NET. 

The following command line simply takes the URL of the DISCO 
document to discover. 

c:\temp> disco.exe http://localhost/math/math.disco 


This generates an output file (results.discomap) that contains in- 
formation about the Web Services discovered at the specified URL 
(see Figure 1). It also downloads all the .disco and .wsdl documents 
that were discovered. 

There is also a command-line utility called wsdl.exe that can 
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Phttp:/flocalhostimathimath.disco 


~ <discovery xmins="http:/ /schemas .xmilsoap.org/disco/"> 
<discoveryRef ref="related-services/default.disco® /> 
<contractRef ref="http:/ /localhost /math/math.asmx? 
wsdl* docRef="mathdocs.htm 
xmins="http:/ /schemas.xmisoap.org/disca/scl/" /> 


generate Web Service proxies from WSDL documents or the | 
.discomap files generated by disco.exe. You can run it like so: 


c:> wsdl resuls.discomap 


Visual Studio .NET provides a nice user interface for discover- 
ing the Web Services available at a given endpoint. In order to use 
this, go to Project | Add Web Reference and type in the URL to the 
.disco file that you want to discover (see Figure 2). This command 
also allows you to add a reference to the selected Web Service to a 
Visual Studio .NET project. This automatically generates the proxy 
code (just like wsdl.exe) and adds it to the Visual Studio .NET 
project within a distinguished namespace. 

Notice that once you've directed the dialog to a .disco file, it 
displays the raw file in the left pane and provides links to the 
WSDL document (View Contract) and the documentation file 
(View Documentation) in the right pane. Those are just links to 
the contractRef element's ref and docRef attribute values. If the 
DISCO document contains links to other DISCO documents 
(through discoveryRef elements), they also show up as links that 
can be navigated in the right pane. 

Clicking on the View Contract link displays the WSDL docu- 
ment referenced in the .disco file, as shown in Figure 3. Clicking the 
View Documentation link displays the document referenced in 
the .disco file (typically HTML-based), as shown in Figure 4. 


DISCO Redirects 


Up to this point, all of the examples have required the client to | 
specify the exact address of the .disco file on the server. In most | 
situations prospective clients won't know the exact address of the | 
.disco file, so DISCO also makes it possible to provide hints in the | 
vroots default page. 

If the vroots default page is 
an HTML document, you can 
use the LINK tag to redirect the 
client to the .disco file: 

<HTML> 


~ <defirnitions 


DISCO and Dynamic Discovery 

The DISCO discovery process just described relies on static 
documents and hardcoded references to the supporting resources. 
But DISCO also provides a dynamic discovery mechanism. To 
enable dynamic discovery, a .vsdisco file like the one shown here 
must be placed in the desired vroot. 

<dynamicDiscovery 

xml ns="urn: schemas -dynamicdiscovery:disco.2000-03-17"> 
</dynamicDiscovery> 
Notice that the root element is now named dynamicDiscovery and 
it belongs to a different 
namespace (urn:schemas- 
dynamicdiscovery:dis- 
co.2000-03-17). 

Requests for .vsdisco 
files are handled by Sys- 
tem. Web.Services. Discov- 
ery.DiscoveryRequestHandler, 
which dynamically gener- 
ates a DISCO document 
based on the resources 
found in the target vroot. 
This document will look 
just like the static DISCO documents described earlier. 

To generate the document, DiscoveryRequestHandler searches 
recursively through all subdirectories, looking for .asmx and .disco 
files. All .asmx files that are encountered are added to the DISCO 
document asa contractRef element. All .disco files found are added 
to the DISCO document as a discoveryRef element. The resulting 


<taml version="1,0" encoding="utf-8" 7> 


xmins:s="http:/ fw w3.org/2001/XMLSchema’ 


<HEAD> 
<link type="text/xml]' 
rel='alternate' 
href="math.disco'/> 
</HEAD> 


xmins: http="http:/ /schemas.xmisoap.org/wsdl/http/" 
xmins:mime="http:/ /schemas .xmilsoap.org/wsdl/mime/" 
xmins:tm="http:/ /microsoft.com/wsdl/mime /textMatching, 
xmins: soap="http:/ /schemas .xmisoap.org/wsdl/soap/" 
xmins: soapenc="http:/ /schemas.xmilsoap.org /soap /encodir 
xmins: sO="http:/ /wwwdevelop.com/disco-sample" 
targetNamespace="http:/ f/www.develop.com/disca- 
sample” xmins="http:/ /schemas.xmilsoap.org/wsdl/"> 
<Lypes> 
- <sischema attributer ormObefault=" qualitied’ 
slementF ormDefault=" qualified’ 
targetNariespace="http:/ f/www.develop.com/disco 
-sample*> 
- <s:slement name="Add*> 
- <s:complexType> 
~ <si sequences 
<s:aloment rainOccure=" 1° 
maxQccurs="1" name="x" 
type="s:double" /> 
«esielement minGccurs="1" 
maxOccurs="1" name="y" 
ye="s:doubl 


</HTML> 


If the vroot's default page is an 
XML document, you can use the 
xml-stylesheet processing in- 
struction to accomplish the 
same thing: 


<?xml-stylesheet type="text/xml" 
alternate="yes" 
href="math.disco"?> 


With these redirects in place, cli- 
ents can simply point the dis- 
covery tools to the vroot and 
they will be automatically redi- 
rected to the specified .disco file 
(see Figure 5). 


Figure 3 Viewing the WSDL Document 
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document looks just like the 
static documents that were 
shown earlier. 

For example, consider this 
Web Service directory layout: 


Tid Wen aeterence cece 


\inetpub 
\wwwroot 
\foo (vroot) 
fool.asmx 
foo2.asmx 
web.config 
foo.vsdisco 
\bar 
bar.asmx 
\baz 
bazl.asmx 
baz2.asmx 


An HTTP request for 
foo.vsdisco produces the 
DISCO document that is illus- 
trated in Figure 6. 

It is possible to specify di- 
rectories that should be ex- 
cluded from the discovery 
process through the exclude el- 
ement, like so: 


Add 
Test 
To test, click the ‘Invoke’ button, 


SOAP 


<dynamicDiscovery 
xml ns="urn: schemas - 
dynamicdiscovery:disco.2000- 
03-17") 
<exclude path="_vti_cnf" /> 
<exclude path="_vti_pvt" /> 
<exclude path="_vti_log” /> 
<exclude path="_vti_script” /> 
<exclude path="_vti_txt" /> 
<exclude path="Web References" /> 
</dynamicDiscovery> 
The dynamic discovery mechanism is preferred by most develop- 
ers due to its simplicity, and it is the default mechanism used by 
Visual Studio .NET Web Service projects. When you create a new 
.asmx Web Service project, a dynamic discovery document is au- 
tomatically created. Once again, it’s still necessary to provide the 
proper redirect links to the dynamic .vsdisco file if you want cli- 
ents to be able to reference the vroot directly instead of referencing 
the actual file name. 

As you can see, DISCO makes it possible to discover Web Ser- 
vices on a given server, but it's somewhat limited in scope and 
functionality because it doesn’t attempt to sort Web Service- 
related information into categories to enable more sophisticated 


queries as are possible with UDDI. 


UDDI as a Better DISCO 

UDDI, which is rapidly evolving as a standard, goes beyond 
DISCO by defining how to interact with a full-fledged Web Ser- 
vice information repository. The UDDI specification consists of a 
programmer’s API along with an XML Schema definition of sup- 
porting data structures and messages. 

An operator site implements the UDDI specification and allows 
users to publish their own Web Service information for increased 
exposure and query the site for others’ Web Service information. 
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Figure 5 Redirecting 


Click #ere for a complete list of operations. 
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The follawing is a sample SOAP request and response. The placeholders 
shown need to be replaced with actual values, 


Figure 4 Viewing an HTML Document 


Ironically, UDDI is itself a Web Service—all publish and inquiry 
operations are defined in terms of SOAP messages. 

Microsoft and IBM (who, with Ariba, are jointly developing 
UDDI) both have operating sites up and running today at http:// 
uddi.microsoft.com/inquire and _http://www-3.ibm.com/services/uddi/inquiryapi, 
respectively. Although most large operator sites (like those just 
listed) will allow arbitrary users to publish Web Service informa- 
tion, individual organizations may choose to do their own. 

It's difficult to tell at this point whether UDDI will ultimately 
become centralized or distributed, but recent computing history 
has shown that a distributed model fosters growth. 


What’s in a UDDI Repository? 


UDDI repositories contain information about businesses, ser- 
vices, and service bindings as well as additional metadata for cate- 
gorization purposes. The way UDDI organizes this information 1s 
similar conceptually to how it’s done in a phone book with colored 
pages. UDDI uses white pages, yellow pages, and green pages the 
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If You Are Building Applications Using Visual Studio .NET 


You Need Native Components... 


As developers begin using Microsoft Visual Studio .NET it is important that they be able to take full 
advantage of the benefits of managed code. This can only be accomplished by using controls that were 
constructed specifically for the Microsoft .NET Framework. With native controls, you need not worry about 
how well a particular control supports a particular environment. 


4 - 450 g glasses 


The XtraGrid is the first and most feature rich Grid and Card Vew 
component library for Visual Studio .NET. Written from the ground 
up - using C# - the XtraGrid Suite is optimized to exploit the power 
and flexibility of Microsoft's .NET Framework. From standard two- 
dimensional tables, to runtime grouping and column customization; 
from master/detail relationships, to card views...the XtraGrid has 
all the features you will need to propel your .NET development 
forward and produce cutting edge applications in the shortest time 


possible - all without writing a single line of source code! 


Fuller Leverling 

Andrew i FirstName: Janet 

Vice President, Sales i 
be: 


Features include: 
Full ADO+ Support ¢ Advanced Unbound Mode Support 


Tite: Sales Representative 


: 8 Dr. ‘TiteOfCourtesy: & Ms. 
Automatic Data Grouping ® Automatic Column Sorting 2/19/1952 (BirthDate: 8/30/1963 
&fi4/1992 ' pHineDate: 4/1/1992 


Automatic Data Filtering © True Master-Detail Support 
Advanced Design-Time Support ¢ Full Data Summaries 
View Based Architecture ® Editor Repository 

Intelligent Column Resizing ® Runtime Column Customization 
Preview Pane ® New Item Row ®@ Card View 


And so much more... 


908 W. Capital Way cdiress: 722 Moss Bay Bhad. 
Tacoma : Kirkland 

WA ‘Ragion: WA 
98401 98033 
USA USA 
(206) 555-9489 {205} 555-3412 


Northmoads Crambenp Sauce 
tit Race Nita ‘ 


DEVELOPER EXPRESS Inc. Developer 
www.devexpress.com Toll Free (888) GoDevex International +1 (702) 262-0609 : 


© 2001 Dice.com 


x 


* 


~ = < 


_ Dice is the job site created by IT professionals, 
exclusively for II professionals. And Dice (ets - 
you announce your availability to prospective © 
employers, letting them know you’re ready to work ~ 
now. Find your ideal opportunity at the number — 


One I] Career Site on the Web, www.dice com. 


 http://localhost/foo/foo. vsdisco - Microsoft Internet Explorer 


fle edt 


| http: Mlocalhost/Foo/Foo, vsdisco 


| <?xml version="1.0" encoding="utf-8" ?> 
| - <discovery umins="http:/ /schemas.xmisoap.org/disco/"> 
<contracthef ref="http:/ /localhost/foo/fool.asmx?7wsdl' 
dockef="http:/ /localhost/foo/fool.asmx" 
xmins="http:/ /schemas.xmisoap.org/disco/scl/" /> 
<contractRef ref="http:/ /localhost/foo/foo?.asmx?7wsdl" 
docRef="http:/ /localhost/foo/foo?.asmx" 
gmins="http:/ /schemas .«misoap.org/disco/scl/" /> 
<contractRef ref="http:/ /localhost/foo/bar/bar.asmx?wesdl' 
docRef="http:/ /localhost/foo/bar/bar.asmx" 
xmins="http:/ /schemas.xmisoap.org/disco/scl/" /> 
<contractRef ref="http:/ /localhost/foo/bar/baz/bazl1.asmx? 
wsdl" docRef="http:/ /localhost /foo/bar/baz/baz1.asmx" 
amins="http:/ /schemas.xmisoap.org/disco/scl/" /> 
<cantractRef ref="http:/ /localhost/foo/bar/baz/baz?.asmx? 
wsdl" dockef="http:/ /localhost /foo/barfbaz/baz?.asmx" 
xmins="httpi/ /schemas.xmisoap.org/disco/scl/" /> 
</discovery> 


Figure 6 A DISCO Document 
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low pages include 
categories based on standard 
taxonomies, and the green 
pages include the technical 
specifications and references 
(see Figure 7). UDDI registries 
support several types of look- 
ups tailored for a variety of dif- 
ferent user groups. 

A UDDI registry contains 
four main types of information: businesses, services, binding tem- 
plates, and tModels. Each business in the registry exposes basic 
information such as name, address, and contact info, as well as 
technical information related to its services. Each of the services 
consists of technical/business descriptions and categorizations. 
Each service also exposes binding template information that de- 
scribes how to connect to and communicate with the given service 
(see Figure 8). 

The information provided by services and their binding tem- 
plates isn't always sufficient to determine compatibility. Simply 
knowing where to connect and how to communicate is just the 
first step; you also need to know the interface contract and its 
associated behavior. A tModel is essentially a technical fingerprint 
used to describe these things (much like a component category in 
COM). tModels are used as binding template metadata to help 
users determine if they're compatible with a given service based on 
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Figure 8 Binding Information 
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interface, behavior, or some other concept. tModels are 
just opaque identifiers that are registered with the UDDI 
site to allow for more precise, application/domain- 
specific identification. 


UDDI Programmer’s API 

The UDDI Programmer's API is divided into two groups 
of operations: inquiry and publishing. The inquiry API 
provides operations for retrieving information from the 
registry, while the publishing API provides operations for 
publishing information to the registry. 

Figure 9 describes the UDDI inquiry operations. Any- 
one can use the inquiry APIs without being authenticated 
by the operator site. The find_XXX operations allow users 
to perform criteria-based queries for businesses, services, 
bindings, and tModels. The following code illustrates 
how to perform a business lookup by the company’s name 
(in this case it’s Microsoft). 
<?xml version="1.0" encoding='utf-8'?> 
<s:Envelope 

xmlns:s="http://schemas.xmlsoap.org/soap/envelope/'> 
<s:Body> 
<find_business generic="1.0" xmlns="urn:uddi-org:api"> 
<name>Microsoft</name> 
</find_business> 
</s:Body> 

</s:Envelope> 
The result of the find_business operation is a list of businessInfo 
elements that contain information about its services, as shown in 
Figure 10. 

As you can see, invoking the UDDI find_business API is simply 
a matter of constructing the appropriate SOAP request message 
and sending it to one of the UDDI site endpoints. The SOAP 
response message contains the result of the API invocation. 

If someone had the business key but didn’t know the service key, 


Figure 9 UDDI In 
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Figure 10 Find Business Result 


she could use find_service to search for a service by name, as you 


can see in the following code: 


<?xml version='1.0' encoding='utf-8'?> 
<s: Envelope 
xmlns:s='http://schemas .xmlsoap.org/soap/envelope/'> 


<s:Body> | 

' <find_service generic='1.0' 
xmlns="urn:uddi-org:api' 
businessKey='0076B468-EB27-42E5-AC09-9955CFF462A3'> 
<name>UDDI Web Services</name> 

</find_service> 
</s:Body> 
</s:Envelope> 


The result of the find_service operation is a list of serviceInto 
elements containing the service details of those elements that 


matched the search criteria (see Figure 11). 
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The get_XXX operations allow users to retrieve the details of a 
particular business, service, binding, or tModel. Once a service 
identifier has been obtained (such as after a call to find_business 
or find_service), you can call get_serviceDetails to retrieve a full 
report of the specified service's details, as shown here: 


<?xml version="1.0' encoding="utf-8'?> 
<s:Envelope 
xmlns:s='http://schemas.xmlsoap.org/soap/envelope/'> 
<s:Body> 
<get_serviceDetail generic='1.0' 
xmins='urn:uddi-org:api'> 
<servicekey>D2BC296A-723B-4C45-9ED4-494F9E53F1D1 
</servicekey> 
</get_serviceDetail> 


Figure 12 Get Service Detail Example. 
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</s:Body> 


</s:Envelope> Figure 14 Save Business Example 


The result of this operation is a businessService element that con- 
tains all the information about the specified service (see Figure 12). 

Figure 13 describes the UDDI publishing operations. The save_ 
XXX operations allow users to register new information or update 
existing information. Figure 14 shows how to save new business 
information to the registry. The delete_XXX operations allow us- 
ers to remove information from the registry. Since the publishing 
APIs alter the operator site’s registry, user authentication and en- 
cryption is required before performing a publishing operation. 
Users can authenticate themselves through get_authToken opera- 
tion, specifying a user name and password. The site will return an 
authentication token that is used in all future publishing opera- 
tions. Users can then use the discard_authToken operation when 
they are finished publishing to invalidate the authentication token 
for future use. For examples showing how to use the publishing 
API, see the UDDI specification and related whitepapers. 

Microsoft provides the UDDI SDK to help simplify writing 
UDDI client applications against the UDDI programmer's API. 
The UDDI SDK (see http://msdn.microsoft.com/nhp/Default.asp?content- 
id=28001204) hides all traces of XML/SOAP by allowing the devel- 
oper to work with native objects, as shown in Figure 15. The latest 
version of the UDDI SDK, 1.75, is designed for use in conjunction 
with the NET Framework. 
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Microsoft Visual SourceSafe® database. Discovery-driven Applications 


One of the main benefits of UDDIT’s richer data model and more 
advanced inquiry API is that developers can build their applica- 
tions around certain types of Web Services, each with the same 
technical specifications, interfaces, and protocols that can be dis- 
covered at runtime (just like COM component categories). This 
allows applications to automatically take advantage of new and 
improved Web Services (of that specific type) that are published 
after the application ships. Building applications with this func- 
tionality requires the lookup and categorization features offered 
today only by UDDI. 

However, even though it’s technically possible to build discov- 
ery-driven applications, most developers won't do it. Developers 
want to choose their business partners a priori so they can estab- 
lish strong relationships based on quality assurance and future 
legal liabilities. No serious developer is going to allow the inclusion 
of some hacker’s completely untested service to debilitate his or 
her aggregate application. 

: . This is exactly why COM component category-based applica- 
Shred nib — > sourcegear, tions never gained wide acceptance in the industry. And since 

oo ia aaa most of today’s UDDI hype revolves around this type of discov- 
ery-driven application, it's unclear as to how much better this 


Convenience — Access over any TCP/P connection 
Performance 10-12 times faster than RAS or VPN 
Securit Optional 128-bit encryption 

Cross-Platform Windows and UNIX clients available 
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beefed-up API will be compared to something that 
is more primitive like DISCO. 

If the information in the existing UDDI reposi- 
tories is a sign of future acceptance, it's not looking 
good. If you browse some of the test UDDI sites, 
youll notice that there is plenty of yellow page in- 
formation (like business name, business details, and 
so forth), but very little technical information (such 
as contract information or WSDL documents). 

Developers using DISCO today have found it 
simple and effective, and they retain complete con- 
trol over the discovery process. Moving to UDDI | 
increases the complexity by an order of magnitude | — 
and forces developers to either relinquish controlto | 
a centralized UDDI operating site or implement 
their own. It’s hard to imagine that many will rush 
to implement that solution. 


A Compromise: UDDI-Lite 

A compromise between DISCO and UDDI Figure 1 16 
might be the best solution. At a recent XML conference, I dis- 
cussed this topic with fellow MSDN Magazine columnist Don Box. 
In response, he hacked out a cool sample that we dubbed UDDI- 
Lite. The idea behind this sample was to provide a centralized Web 
Service repository for organizations that would be easy to main- 
tain, and would integrate with all of the existing .NET DISCO- 
based tools. | 

To accomplish this, we decided to store the Web Service infor- 
mation in a SQL Server™ database. We provided an ASP.NET front 
end that developers would use to register and unregister Web Ser- 
vice information—the same information that a developer would 
put in a .disco document. Any developer in the organization could 
easily add new entries that would be exposed through a central 
.disco document (see Figure 16). 

Then when clients request the uddilite.vsdisco file in the sample's 
vroot, it’s automatically generated from the information stored in 
SQL Server. This is accomplished by mapping requests for 
uddilite.vsdisco to the ASP.NET System.Web. UI.PageHandler- 
Factory class. This causes the runtime to treat the uddilite.vsdisco 
file just like a standard ASP.NET page, which is shown in Figure 17. 

This sample could easily be extended to support more advanced 
queries such as one to find all services that support the specified 
WSDL port type, but it’s much simpler than UDDI and it allows 
organizations to retain control. 


File | 


Into 


Conclusion 


Once Web Services have been exposed, it makes sense to pub- 
lish them through a mechanism that supports machine-driven 
discovery. DISCO was initially a Microsoft discovery protocol that 
was never meant for more than simple document-based lookups. 
DISCO is ultimately limited by the type and depth of the informa- 
tion that it provides. Microsoft has also been heavily involved in 
the development of UDDI, which is receiving a lot of attention. 
How successful it will be ultimately remains ta,be seen. The bot- 
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Figure 17 ASP File 


tom line is that DISCO works today and it can help you get more 
mileage out of your .NET Web Services with little effort. For the 
future, keep your eye on UDDI developments. 


Send questions and comments for Aaron to xmlfiles@microsoft.com. 


Aaron Skonnard is an instructor/researcher at DevelopMentor, where he develops the XML and 
Web service-related curriculum. Aaron coauthored Essential XML Quick Reference (Addison- 
Wesley, 2001) and Essential XML (Addison-Wesley, 2000). Get in touch with Aaron at http:// 
staff.develop.com/aarons. 
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There are two main types of porting: | 
porting from platform to platform and 
porting from architecture to architecture 
within the current operating system. 
Porting from platform to platform involves 
moving an application to a different | 
Operating system. The degree of change 
required can be anywhere from minor to” 
drastic. Porting from architecture to 
architecture involves moving to a different 
type of hardware (for example, hardware 
with different physical properties) within 
the current operating system. One example 
of this type of porting is the transition from 
16 to 32 bits that accompanied the 
introduction of the Intel 80386 in 1985. 
Another is the current migration from 32 
bit architectures to 64 bit architectures. In 
most cases, this type of porting requires a. 
considerable amount of effort. 


: The same major problem tends to occur And you won’t have to worry about 
in any porting process regardless of the Insure++ disrupting your development 
nature of the particular port: if you port | Den SCOPE testdlll.cpp * 21 cycle. Insure++ is available on all major 
buggy software, the bugs multiply when a= now DuORDCA2>s UNIX platforms, including Linux, AIX, 
they reach the new platform or architecture DEC, HP, SGI, and Solaris. On UNIX, you 
and soon become overwhelming. Why do can install and run Insure++ with a few 
SO many bugs appear when porting? simple commands and instantly find bugs. 
Because porting is essentially a type of If you develop on Windows, you can 
mutation testing. When you port code, you | Integrate Insure++ into Microsoft Visual 
essentially create what is sometimes called _ C++. 
an “equivalent mutant’— a version of the 
Original code with minor changes that 
should not affect the outcome of your test | 
cases. | have found that when you create | 
and run equivalent C++ mutants, a lot of | 
very strange errors will occur if the original 
code contains problems or ambiguities | 
such as: missing or incorrect copy 
constructors, missing or incorrect. 
constructors, code that was not initialized | 
in the correct sequence, problems with the | 
Operation of pointers. 
If you ensure that your code is free of | 
such problems before you port, you will 
improve the quality of the application on 
the new platform/architecture, streamline — 
the porting process, and make the original . 
application more robust and reliable. 


“Insure++ will easily save us weeks of debugging time and | strongly 
recommend it to anyone doing development.” 


— Michael Babcock, Jim Henson’s Creature Shop 


Insure++® is an automatic runtime error- addition to testing with Chaperon, you can 
detection tool for C/C++ applications; it check your code using Source Code 
detects a variety of problems, including Instrumentation. This feature performs a 
memory corruption, memory leaks, pointer detailed, comprehensive code analysis that 
errors and I/O errors. It works like an X-ray flushes out the most subtle errors — errors 
machine, automatically exposing hidden that take the most skilled developer weeks 
defects. When you test your code with to find. To further speed up your debugging 
Insure++, you get incredibly thorough results process, Source Code Instrumentation 
employs coverage analysis, enabling you to 
track the progress of your code testing. 
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To release every product with confidence, 
download a demo of Insure++ today 


You can send messages to Insra, the error-display GUI, at www.parasoft.com/ms2 or for more 
then click to see full error explanations and stack trace information call (888) 305-0041 
information. : 


with minimal work. Each time Insure++ finds 
an error, it reports its exact location and 
provides a complete explanation, helping you 
make speedy repairs. 


Insure++’s latest breakthrough technology — 
Chaperon—allows you to detect errors 
without recompiling or relinking. For 
Situations that call for a quick overview of 
your code, Chaperon gives you a fast, 
accurate analysis while uncovering 
extremely complex errors such as 
memory leaks, memory reference 
errors and memory corruption. In 
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Establishing Relationships Between Rowsets with ADO.NET 


JOHNNY PAPA 
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ML has taken the development community | 

by storm. But until the introduction of 
ADO.NET, the basic tenets of XML have not been 
fully implemented by a data access toolset. Because 
ADO.NET has XML at its core, it can handle full- 
feature XML data structures as well as relational 
data structures. 

This wasn't always the case. ADO 2.x required 
the use of either the hierarchical recordset struc- 
ture (which was very slow and not sufficiently in- 
tuitive) or the standard Recordset object with a 
matrix of columns and rows, in order to manage 
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hierarchical data in an object. The Recordset object in ADO 2.x | 
manages a two-dimensional matrix very well, but it's not great for _ 


representing hierarchical data. 
In the previous two installments of the Data Points column I 


began a series on writing applications using the DataSet and other | 


features of ADO.NET (see the November 2001 and January 2002 
issues of MSDN* Magazine at http://msdn.microsoft.com/msdnmag/issues/ 
01/11/data/data0111.asp and http://msdn.microsoft.com/msdnmag/issues/02/ 


01/data/data0201.asp). In the January column, I demonstrated how | 
you can use a DataSet to retrieve data, track modifications made | 


by the user, and send the data back to the database. 
This month I will build on this application so that 
the user can save several rows of changes for customers, 
orders, and order details all in one shot. Using 
ADO.NET, this type of relational yet hierarchical struc- 
ture can be retrieved from and applied to a database in 
one fell swoop. 

Using Visual Basic’ .NET, I'll show you how to use a 
business services application that’s written in C# to re- 
trieve customers, orders, and order details from the 
Northwind database and plug them into a DataSet. 
The DataSet will contain three DataTables, which I'll 
link using DataRelation objects to create a hierarchical 
data structure. At that point, I'll load the information 
into the presentation tier. Finally, Pll present examples 
that use the DataSet to save several rows of data to the 
database all at once. : 

The application built in this article can be broken 
into two distinct projects: a Windows’-based app to 


 DataRowCol 
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Figure 4 ADO. NET DataSet 
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handle the business rules and data manipulation 
calls. Pll start by examining the Windows Form 
_ (written in Visual Basic .NET), which allows the 
user to interact with the application. Then, I'll show 
how the business services (written in C#) can re- 
trieve the hierarchical data and make database 
modifications. In the business services, I'll explore 
__ class inheritance as well as the overriding and over- 
loading of methods. 


~ DataRelations 

The key to managing data in ADO.NET is to 
understand the convergence of hierarchical and relational data 
structures. An ADO.NET DataTable stores a two-dimensional 
rowset, which is similar to the way you used the Recordset in ADO 
2.x. Currently, if you take two DataTables within the same DataSet 
object and create a relationship between them using a DataRelation 
object, the result is a hierarchical structure. A relational database 
such as Northwind is now represented with its true relationships. 
In the past, you would have had to combine the customers and 
their orders into a single rowset, thus producing a flattened data 
structure by forcing the data into a single two-dimensional matrix. 
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present the data to the user andaclass library projectto Figure 2 The Customers 
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Figure 3 The Customer’s Orders 


Now, using a DataSet and its child objects, you can maintain the 
relational and hierarchical structure. Figure 1 shows how the DataSet 
object can contain multiple DataTable and DataRelation objects. 


The DataGrid 


Let’s look at a Windows Form that controls the presentation of 
this application. The form frmMain.vb contains a DataGrid con- 
trol that will be filled with the customers, their orders, and each 
order’s details. The DataGrid is a server control that is easily ma- 
nipulated to render a rowset by binding itself to a DataSet. Because 
the DataSet will have a hierarchical structure, the DataGrid will 
automatically adjust to that structure by displaying all customers 
first. All changes made to the DataGrid’s data are reflected onto the 
underlying DataSet. The DataGrid shows the customer rows with 
a+ sign to the left of each row (see Figure 2). This allows the user to 
drill down into each customer’s child records (in this case, the 
customer's orders). 

The DataGrid allows the user to navigate up and down the par- 
ent and child relationships from a customer to their order and 


Figure 4 LoadData 
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onto the order details. The grid allows for changes to be 

made at each level of the hierarchy. So whether a row is 
deleted, added, or simply modified, the DataGrid man- 
ages the changes. All changes are then reflected in the 
underlying DataSet. To navigate to the child records, 
simply click on the link for the DataRelation, called 
CustomerToOrder (see Figure 2). 

After clicking on the CustomerToOrder DataRela- 
tion hyperlink in the DataGrid, the customer's orders 
will be displayed (see Figure 3). The grid can bea useful 
tool to represent and manage multiple levels of hierar- 
chical data and their relationships. 


Public Class frmMain 
Inherits System.Windows. Forms. Form 
Private m_oDS As DataSet 


To load the data into the DataGrid, I’ve declared and 
instantiated the business services’ CustomerOrder class. 
Then the DataGrid's data binding settings are cleared 
and the business services’ CustomerOrder object is 
called to retrieve the DataSet into the frmMain class 
property m_oDS. Now that the DataSet is local, I bind 
it to the DataGrid, loading three levels of related rowsets into the 
DataGrid (see Figure 4). 

The user can interact with the data and then save the changes to 
the database by clicking on the Save button. Figure 5 shows the code 
in which the SaveData method declares and instantiates the busi- 


Figure 5 The SaveData Method 


ness services’ CustomerOrder class. If no changes were made to 
the DataSet, the method is exited. I check the HasChanges method 
of the DataSet to see if any changes were made to the data. 

If there are changes to the data in the DataGrid, I set the 
oDS_Delta DataSet variable to contain the changed rows in the 
original DataSet. The GetChanges method of the DataSet copies 
the changed rows from the DataSet and puts them into a new 
DataSet called oDS_Delta. This reduces the network traffic since I 
pass only the modified rows to the business services. 


The Business Services 
Up to this point the code is the same whether the DataGrid is 


Figure 6 GetData Method of the Base Class 
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// Return Value: DataSet 

// Purpose: Retrieves. all items 
( 
public virtual Dataset GetData() 

{ 


None. 
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Create a new. ‘Dataset 
new DataSet(); 
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iL Return. the DataSet 
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Figure 7 SaveData Me 


// Public Method 
i] Overloaded: 


i ae 
eo 
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string Msg - = 
ae 
. Save the data 


try 
if (on. State 


ae 


} 
finally 
| 


ei whi 


} 


return sMsg; 


loaded with a single DataTable or the DataSet contains multiple 
related DataTables. Where things really begin to change is in the 
business services. The 
code in the following ex- 
amples shows how to de- 
fine and create instances of 
the Customer, Order, and 
OrderDetail classes. These 
classes will be used to re- 
trieve and save data to and 
from the database. Since all 
three classes need to re- 
trieve and save data in the 
same manner, | have cre- 
ated a base class, Base_BusinessServices, from which all three 
classes can inherit properties and methods. 


Base Classes and Inheritance 


The Base_BusinessServices class has two public methods: 
GetData and SaveData. It also contains a protected method called 
InitializeConnection, which defines the connection string. I made 
this method protected so that it can be accessed by any class that 
inherits from or implements the Base_BusinessServices class. The 
GetData method, shown in Figure 6, works the same way whether 


the data retrieved is customer, order, or order detail data. There- 
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Figure 8 The Customer Class and its Constructor 


fore, I can use this method in the base class and the Customer, 
Order, and OrderDetail classes can inherit it. 

Lalso created a fifth class called CustomerOrder, which creates 
an instance of each of the Customer, Order, and Order Detail classes. 
The CustomerOrder class also inherits from the Base_Business- 
Services class since it needs the GetData and SaveData methods. It 
is not necessary for this class to inherit from the base class, but it 
provides a means to discuss overriding an inherited method. You 
may have noticed in Figure 6 that the GetData method was declared 
with the virtual keyword. This tells any class that inherits from this 
base class that it may override the method. In this application, I 
wanted to have the GetData method execute code other than what 
was in the base class, so I chose to override this method. 

The Base_BusinessServices class also contains a SaveData 
method, as shown in Figure 7. Since I used the virtual keyword on 
this method, any class that’s derived from this base class will be 
able to override this method. Notice that the SaveData method 


uses the try-catch-finally construct to apply the data changes to 
the database. It opens the connection to the database and executes 
the SqlDataAdapter object’s Update method. 

Each row of the DataSet is traversed in the same order that it was 
sent to the SaveData method. Assuming six rows were changed (as 
shown in Figure 7), the corresponding SqiCommand would be 


issued in the order that the rows appear in the DataSet. 


The Inheriting Classes 


The Base_BusinessServices class contains the basic functional- 
ity that the Customer, Order, and OrderDetail classes require. 
Therefore, by having each of these classes inherit from the Base_ 
BusinessServices class, the GetData and SaveData methods do not 
need to be redefined. Figure 8 shows the Customer class. (The Or- 
der and OrderDetail classes are very similar to the Customer class, 
differing only in their SQL statements.) 

To inherit the Base_BusinessServices class, the Customer class's 
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Figure 9 The CustomerOrder Class and its Constructor 
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definition is followed by a colon and the name of the Base_Bus- 
inessServices class, as shown in Figure 8. The constructor for the 
Customer class is used to set up the SqlDataAdapter object. The 
SqlDataAdapter takes four SqiCommand objects, each of which 
represents one of the four main types of data manipulation and 
retrieval in SQL: SELECT, INSERT, UPDATE, and DELETE. First, 
I created the SqlCommand to represent the query that retrieves the 
customer data viaa SELECT statement. Then I created the SqlCom- 
mand to represent the query that updates the customer data via an 
UPDATE statement, and so on. Finally, I created a SqiDataAdapter 
object and assigned the corresponding SqliCommand object to 
each of its command properties. 


The CustomerOrder Class 


The CustomerOrder class puts all of the pieces together in the 
business services. It combines the customer, order, and order de- 
tail data and relates them within a single DataSet. The constructor 
for CustomerOrder defines and creates the instances of each of 
these classes, as shown in Figure 9. 

The GetData method overrides the base class Base_Business- 
Services GetData method using the override keyword (see Figure 
10). Here is where the data from the three classes is combined into 
a single DataSet. The GetData method of each of the Customer, 
Order and OrderDetail classes is called and a DataTable is re- 
trieved from each. Then each DataTable is added to a new DataSet. 
Stopping at this point in the process would yield a DataSet com- 
prised of all three rowsets, but the data would not yet be linked ina 
hierarchical structure. 

To relate the data, my next step was to create a DataRelation 
object for each relationship. First, I created the relationship that 
links the individual customers to their orders. The DataSet con- 
tains a Relations collection, which has an Add method. I used this 
method to create the new DataRelation object and add it to the 
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Figure 10 GetData Method of the CustomerOrder Class 
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DataSet. I called the relationship CustomerToOrder and passed to 
it the columns from the DataSet that defines the relationship. By 
establishing this relationship, you can traverse the DataSet from a 


- customer to his orders. 


To complete the relationships, I added another DataRelation to 
link each order with its order details. With both DataRelation ob- 
jects linking the three DataTables within the DataSet, I can walk 
the tree from the parent to its child records. At this point I’m ready 
to return the DataSet to the presentation services (the Windows- 
based app, in this case). 

Once the user saves the data modifications in the Windows- 
based app, the delta DataSet is passed to the business services’ 
CustomerOrder class via the SaveData method (shown in Figure 
11). The CustomerOrder class’s SaveData method overrides the 
SaveData method from the inherited base class and uses the try- 
catch-finally construct to save the data to the database. 

First, the connection to the database is defined and opened. 
Next, a transaction is begun on the connection. Creating the trans- 
action allows the code to use a two-phase commit on the data 
changes. The first phase prepares the data changes, and the second 
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Figure 11 SaveData Method of the CustomerOrder Class 


phase writes the data changes if there are no problems and the data 
doesn't have to be rolled back. 

Next, each of the Customer, Order, and OrderDetail classes'’s 
SaveData methods are executed. If any one of them fails, it will 
return an error message and an exception will be thrown in the 
try-catch-finally construct. Then the exception transfers the next 
execution to the catch clause where the transaction is rolled back. 
Unlike previous versions of Visual Basic, Visual Basic .NET and 
C# error handling techniques do not rely on errors bubbling up 
the call stack. Instead, it is sometimes recommended that your 
methods return a status that can be evaluated to determine if an 
error occurred. In the SaveData methods, a return value of a string 
message means that an error occurred while saving the data. An 
empty string indicates that the method encountered no difficul- 
ties. Assuming that each of the Customer, Order, and OrderDetail 
class’s SaveData methods executed without incident, the transac- 
tion is committed and control is passed back to the calling Win- 
dows-based app. 


Wrapping Up 

This example shows how to create a business service (the Class 
Library written in C#) and a presentation service (the Windows- 
based app with the Windows Form written in Visual Basic NET) 
using different .NET languages. To execute the application, com- 


pile the two projects and make sure that the Windows-based app 
references the business services assembly. Being able to relate dif- 
ferent rowsets so that they resemble a relational database with one- 
to-many relationships makes the use of XML for data manipulation 
even more powerful. Using ADO.NET you don't need to combine 
rowsets through SQL joins or manipulate an XML document di- 
rectly. Or course, the option of joining rowsets into a single rowset 
is entirely feasible in ADO.NET. In fact, to retain backward com- 
patibility, you could return a single rowset of customer, orders, and 
order details to an application. 

In this installment of the Data Points column I showed you how 
to take advantage of the DataSet by relating rowsets to one another 
and creating a single interface to modify all related rowsets. I also 
demonstrated how to use inheritance to derive methods and prop- 
erties from a base class when there are commonalities that can be 
reused. All of the code used in this article can be downloaded from 
the MSDN Magazine Web site at http://msdn.microsoft.com/msdnmag/ 
code02.asp. 


Send questions and comments to Johnny at mmdata@microsoft.com. 


Johnny Papa is VP of Information Technology at MJM Investigations in Raleigh, NC and the 
author of Professional ADO 2.5 RDS Programming with ASP 3.0 (Wrox, 2000) and contributing 
author of Professional XML Databases (Wrox, 2000). You can reach him at 
john@lancelotweb.com. 
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Data Binding Between Controls in Windows Forms 


BINO ESPOSITO 


Dp: binding is a very powerful feature of most applications, 
and Windows’ Forms and Web Forms applications are clearly 
no exception. Data binding is the process of retrieving data from a 


source and dynamically associating it with a property of a visual 
element. Depending on the context in which the element will be — 


displayed, you can map the element to an HTML tag, a Microsoft’ 
NET Web control, or a Windows Forms control. Generally speak- 
ing, data binding is not a platform-specific feature, but this does 
not mean that different application models cannot have different 
implementations of it and even offer a different set of features. 

In this column, I will discuss some underpinnings of the Win- 
dows Forms implementation of data binding. I'll do that by in- 
cluding both practical hands-on examples and insights on the 
Windows Forms object model. To demonstrate how to take full 
advantage of the built-in data binding mechanism, I'll discuss a 
Windows Forms-specific feature that combines the best capabili- 
ties of the Windows Forms DataGrid control (do not confuse tt 
with the DataGrid Web server control that I've covered in past 
issues) and two key ADO.NET objects, the DataSet and the 
DataRelation. These three elements make .NET Windows-based 
applications capable of implementing master/details schemas in a 
rather codeless and declarative way. 

The Windows Forms DataGrid control has the ability to detect 
relationships within the data of a bound DataSet and can auto- 
matically provide for a hierarchical view of this data. This aspect of 
data binding is fully covered in the Data Points column in this 
issue of MSDN’ Magazine. By contrast, Pll show you the structure 
of the form-binding context and how to develop custom controls 


that automatically retrieve their parent and synchronize with its | 


currently selected item to provide a hierarchical view. To illustrate 

my points, I'll start from one of the samples in the Microsoft .NET 
Framework SDK. Under the samples\quickstart\winforms\sam- 
ples\data\masterdetails folder, there is an interesting application 
that connects to a Web Service and downloads a DataSet made up 
of customers and related orders. The data is packed in a single 
DataSet using two distinct tables—Customers and Orders. Once 
onthe client, the rows in the tables are correlated on the employeeid 
column by creating an appropriate DataRelation object (see the 
Data Points column in this issue). So far, so good—but the most 
interesting part is still to come. 


controls. One acts as the master grid and displays information 


i 
i 
i 
i 


| displays the orders that re- 


about the customers. The other plays the role of the detail grid and 
shows all the information about the orders that the selected cus- 
tomer has issued. What’s amazing is that in all the source code 
there is no place where the two DataGrid controls are explicitly 
connected to each other. 
No instruction ever tells 
one of them about the ex- 
istence of the other. Yet the 
detail grid automatically 


late to the customer cur- 
rently selected in the 
master grid. Is there a rea- 
sonable explanation for 
this cool, apparently magi- 
cal behavior? In this column, I'll try to unveil the mystery and 
untangle the details behind automatic data binding in Windows 
Forms applications. 


Collecting Clues and Traces 


Although I’ve spoken of master and detail DataGrid controls, in 
no place in the .NET Framework sample code are the two grids 
ever assigned these roles. The only visible link that ties the two 
grids together is the content of the DataMember property. The de 
facto master grid is bound to the actual master table—Employees. 


master.DataSource = dataset; 
master.DataMember = "Employees"; 


The de facto details grid is bound to a navigation path which 
ends with the name of the relation connecting the two tables. A 
relation represents a parent/child relationship between two Data- 
Table objects. In ADO.NET, a relation is rendered using a DataRe- 
lation object. Assuming EmployeesToOrders is the name of the 
relation, then the details grid is bound to the dataset as follows: 


details.DataSource = dataset; 
details.DataMember = "Employees.EmployeesToOrders"; 


The ADO.NET DataRelation object provides an effective way 
to keep two logically related tables synchronized on the value of a 
common field. The DataRelation object has no direct counterpart 
in the ADO object model. However, if you have ever dealt with the 
ADO data shaping feature and know how it works, you will under- 
stand ADO.NET relations. A data relation can be established only 
between two columns belonging to distinct tables in the same 


Figure 1 Initial Outline of Grid2Grid 


DataSet object. The two columns can have different names, but 
must contain the same data type. To be effective, a DataRelation 
object must be stored in the DataSet’s Relations collection. 

Once a data relation has been created, each row on the parent 
table points to an array of rows on the child table. So, for instance, 
each customer row points to an array of orders—all the orders that 
the particular customer made at a given time. A custom imple- 
mentation of a master/details schema would be needed to retrieve 


Figure 2 Data Relation is Set Up 


46 msdnmagazine Cutting Edge 


and display this collection of child rows. 
But now, as the .NET Framework sample 
shows, this functionality is built into the 
Windows Forms DataGrid control. I’ve 
written a small Windows Forms applica- 
tion to reproduce this behavior. In Figure 
1, you can see the outline of the resulting 
form as it appears in Visual Studio .NET. 


Reproducing the Behavior 


The form layout includes two Data- 
Grid controls named masterGrid and 
detailsGrid which are placed at the top 
and the bottom, respectively. Aside from 
the status bar, no other control partici- 
pates in the application. In Figure 2, you 
can see the core part of the code. 

To make sure that no system features 
could slip in unnoticed, I turned off the 
automatic configuration of data and connection controls. The 
ConfigureDataAdapter method shows how the data is actually 
accessed from the sample Northwind database. The SELECT com- 
mand is a semicolon-separated batch of two SQL commands. Asa 
result, the final DataSet has two tables, Employees and Orders. 
During the form initialization stage, the command is executed and 
the two tables then become related. 

DataColumn dcl, dc2; 


dcl = a 5 é eee ° 
E Automatic Mast out to be of some importance. Although the 
ds.Tables["Employees"].Columns["employeeid"]; eckieenlanne ee! f E 8 
dc2 = ds. Tables["Orders"].Columns["employeeid"]; DataGrid control exposes a CurrentCell- 
pauave lation mela ts) Changed event, it is only useful for detect- 
rel = new DataRelation("EmployeesToOrders" ; : : 
del, dc2); ing changes that occur interactively. In other 
geroletionsAddtrel ds words, the following event handler fires your 
code only when the currently selected cell 
on the master grid changes in response to a 
user click. 


The relation associates orders with employ- 
ees based on the common employeeid field. 
The two DataGrid controls are bound to 
data like this: 


masterGrid.DataSource = ds; 
masterGrid.DataMember = "Employees"; 
detailGrid.DataSource = ds; 
detailGrid.DataMember = 

"Employees .EmployeesToOrders” 


Se rrrt~<C<CSti‘i‘i‘a‘CSCCOW®;‘OCOCOC masterGrid.CurrentCel1Changed += 
OrderID OrderDate Total new EventHandler(CurrentCel Changed) ; 


At startup, the two grids are still synchro- 
nized by something else. The following code 
makes the whole sample applet much more 


user friendly. 
masterGrid.CurrentCellChanged += new 


The result of running the code is shown in 
Figure 3. At startup, the first row is selected 
EventHandler(CurrentCelIChanged) ; 


on the topmost grid—the one bound to the aa Forml.Activated += new 
master table. The contents of the bottom- Figure 3 Data Relation in Action EventHandler(CurrentCel1Changed) ; 


You can see the results in Figure 4. The CurrentCellChanged event 
handler updates the caption of the bottommost grid to reflect the 
name of the employee selected in the master grid. You need to 
hook up the form’s Activated event to make sure the code fires 
before the form is actually displayed. 


most grid—the one bound to the output of the relation—is the 
collection of the orders issued by the given employee. As you select 
a new employee on the top grid, the contents of the child grid 
change accordingly. This behavior is easily reproducible. Lets have 
a closer look at how this works. 

The first question I tried to answer was whether there was a way 
to detect the change of the current cell on one of the grids. This 
issue, seemingly unrelated to the master/child problem, turned 


The Relation is Key 


Based on the code in Figure 2, how would you describe the con- 
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tents of the details DataGrid control? It 
looks like the control is bound to the sub- 
set of rows that result from the parent table 
via the relation. How can the details grid 
retrieve these rows? The only confirmed 
link is the data member string and the 
relation. Any attempt to reproduce the 
same master/details schema using controls 
other than the DataGrid is destined to fail 
miserably. Nothing out of the ordinary 
seems to be present in the code for the 
master grid, so let's focus on the details 
grid instead. 

So far I’ve looked at the navigation path 
as a keyword that had a special meaning to 
ADO.NET Instead, it could be simple syn- 
tax recognized by the DataGrid and used 
to pass two distinct bits of information ina 
single shot. The navigation path Table- 
Name.RelationName could therefore be split into two parts: the 
name of the parent table and the name of the relationship. To get 
records out of a relation, though, what you really need is not the 
table name but a living instance of the DataRow object lying be- 
hind the currently selected row in the parent grid. 

The structure of the string assigned to the DataGrid’s Data- 
Member property determines whether the control has to work as 
the details grid or the master grid. If DataMember takes the form 
of TableName.RelationName, then the DataGrid control is de- 
signed to retrieve its contents based on the contents of another 
parent control. The DataGrid and its parent control share the same 
data source object. In addition, the DataMember property of the 
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parent binds to the table with the name that matches TableName. _ 


In the sample application, this is the master DataGrid control. Not 
all controls are good candidates to play the role of the master 
control. They must be data-bound and expose the DataMember 
property. This works for the Windows Forms DataGrid control, 
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Figure 5 A Second Master Grid is Added 
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Orders issued by "Fuller, Andrew" 


Figure 4 Grid2Grid Enhanced 
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but any list control (such as ListBox or 
ListView) could be adapted to work as the 
master. In this case, adapting a control 
means creating a new custom control with 
enhanced capabilities. Likewise, the child 
control can be a DataGrid or any other 
custom control (more on this later). But 
why does a control need to have an active 
role in this kind of automatic master/de- 
tail schema? 

The Windows Forms data binding 
mechanism allows controls to query for 
the data-bound control linked to a mem- 
ber of a given data source. Through this 
mechanism, the details DataGrid can re- 
trieve an indirect reference to the parent 
DataGrid and register for an ad hoc event 
that fires whenever the currently selected 
row changes. The details grid, whose 
DataMember takes the form of TableName.RelationName, requests 
the binding manager for the control bound to the given member 
(TableName) within its same DataSet data source. In this way, two 
DataGrid controls that had no knowledge of each other can auto- 
matically start working together. 

Next, I'll look at what happens if two or more controls are bound 
to the same data source and data member. 


Binding Contexts 


I modified the sample application to accommodate a second 
DataGrid control whose data binding settings are identical to the 
master grid. 


masterGrid.DataSource = ds; 
masterGrid.DataMember = "Employees"; 
anotherMasterGrid.DataSource = ds; 
anotherMasterGrid.DataMember = "Employees"; 


What happens to the details grid? Well, it’s not affected whatsoever 
by the number of potential masters (see Figure 5). No matter which 
master grid you click, the details control correctly de- 
tects the change and properly refreshes. This means that 
the data binding mechanism is a bit more versatile and 
complex. The details control wont get a reference to a 
living instance of another control, but it obtains a refer- 
ence to a component called the binding manager. 

The binding manager is specific to a data source no 
matter how many controls actually bind to it. The bind- 
ing manager presents itself to child controls as a single 
entity to connect to. Then it fires a control-independent 
set of events to indicate selection changes in any of the 
masters. Once a details control has gotten a reference to 
the binding manager, it registers for the CurrentChanged 
event. When the event fires, the details control retrieves 
arguments that represent the data item that corresponds 
to the currently selected row—the parent DataRow ob- 
ject. At this point, the linkage is pretty much complete. 
A control that holds the parent DataRow object and a 
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relation name can easily retrieve the array of rows that constitute 
the details view. The base .NET class impersonating the binding 
manager is BindingManagerBase. A control can query for the bind- 
ing manager through the BindingContext property, a property 
inherited from the base Control class. The BindingContext prop- 
erty returns an object of type BindingContext. 

Actually, BindingContext is just a special collection object, as its 
declaration demonstrates. 

public class BindingContext : ICollection, IEnumerable 
The BindingContext collection manages all binding objects that 
are bound to the same data source and data member. Each binding 
object is represented by an instance of classes that inherit from 
BindingManagerBase. BindingManagerBase is an abstract class; 
the actual classes that you will be working with are CurrencyMan- 
ager and PropertyManager. — 

The PropertyManager class keeps track of a simple binding be- 
tween a data-bound control property and a data source scalar 
value. A more sophisticated role is played by the CurrencyManager 
class. CurrencyManager handles complex data binding and main- 
tains bindings between a data source and all the list controls that 
bind to it or one of its member tables. The CurrencyManager class 
takes care of synchronizing the controls bound to the same data 
source and provides a uniform interface for clients to access the 
current item for the list. Both classes have properties like Current 
and Position. The PropertyManager’s Current property, on the 


® 


other hand, indicates the current property of a data-bound object. 
For example, if you have the Text property of a TextBox bound toa 
particular row/column pair of a data source, the result you get is 
the current value of the Text property. 

The CurrencyManager’s Current property indicates the data item 
behind the currently selected row in the user interface of the data- 
bound list control. If you have a list control (such as a DataGrid or 
ListBox) bound to a DataTable, Current returns the DataRow ob- 
ject corresponding to the control’s item. The data type of Current 
depends on the type of the data source; it will be a DataRowView if 
a DataView is used or it will bea string if the data source is an array 
of strings. The current item in the data-bound master control can 
be interactively set by the user or set programmatically by the 
application using the CurrencyManager class's Position property. 
Position is a get/set property that indicates the zero-based index of 
the current row in the bound data source. Count is the property 
that lets applications know about the number of rows that can be 
found in the bound data source. 

Let’s recap the facts that make automatic master/details schemas 
possible with Windows Forms DataGrid controls. Any DataGrid 
control whose DataMember property is in the form 
TableName.RelationName behaves like the child of a parent/child 
relationship. Needless to say, this works the way it should as long as 
an ADO.NET data relation exists with the given name in the 
DataSet that the grid is using. 
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Figure 6 DetailListView 


- The child DataGrid, which isa list control, utilizes its own bind- 
ing context to get the CurrencyManager for all controls in the form 
bound to the same data source. The child grid registers to handle 
the CurrentChanged event on the binding manager. The event 
passes the DataRow object selected in the parent grid as an argu- 
ment. At this point, the child grid uses the ADO.NET relation to 
retrieve the child rows to show. To accomplish this task, the details 
grid does not need to know about the parent control. 

The next step is demonstrating that any Microsoft .NET control 
whatsoever can be adapted to work as the child of an automatic 
master/details schema. 


Creating a DetailsListView Control 


The DataGrid is not the only type of Windows Forms control 
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that can support this automatic master/details feature. While it’s 
the only control in the .NET Framework to provide this feature, 
custom ad hoc controls are easy to write. Let's enhance a ListView 
control to make it work as the child of a master DataGrid. The 
. ListView control is not data-bound, but this does not mean that it 
cant work in a data-oriented, master/details relationship. Figure 6 
shows the source code of a class called DetailListView, which is 
built atop the ListView control and adds the support needed to 
make the control work in a master/details architecture. The new 
class is declared as follows: 


public class DetailListView : ListView 


{ 
public DetailListView() 


{ 
View = View.Details; 
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FullRowSelect = true: 


} 

For simplicity, I managed to make the control always work in 
Details mode. The user interface is always column-based regard- 
less of the option you select from the Properties box in the Visual 
Studio project. The control class is project-specific and does not 
appear in the toolbox. To put it on the main form of a sample 
application, just drop it on the form and configure it like an ordi- 
nary ListView. When youre finished, open the wizard-generated 
region of code in the form body and replace occurrences of the 
class System.Windows.Forms.ListView with the name of your 
class—in this case, DetailList View. 

The DetailListView control is given two extra properties: 
DataSource and DataMember. The implementation of the control 
you find in the source code is not a full implementation of data 
binding; it is limited to providing the features that allow the con- 
trol to support automatic master/details. This means, for example, 
that DataMember is always expected to take a string like Table- 
Name.RelationName. Another assumption is that the parent con- 
trol is bound to a DataTable or a Data View object. 

When either DataSource or DataMember are modified, a spe- 
cial accessor code runs. It splits the data member in two parts: the 
parent table name and the relation name. 


Array a = m_DataMember.Split(sep); 
m_ParentTable = a.GetValue(0).ToString(); 
m_RelationName = a.GetValue(1).ToString(); 


If both properties are non-null, the protected method AutoBind 
is called. AutoBind looks up the binding context collection of the 
ListView. Bear in mind that BindingContext is available on any 
control derived from Control and is not linked to any support for 
data binding. 


private void AutoBind() 
{ 
CurrencyManager cm; 
cm = (CurrencyManager) BindingContext[DataSource, m ParentTable]: 
if (cm != null) 
leisy 
cm.CurrentChanged += new EventHandler(CurrentChanged) ; 
RefreshList(cm); 
} 
} 


First, the control retrieves the binding manager for the specified 
data source and table. The BindingContext collection returns an 
instance of the CurrencyManager class. In this case, you can be 
sure about the return type. 

You could also replace CurrencyManager with BindingManag- 
erBase. The DetailListView class then registers a handler for the 
CurrentChanged event and refreshes its user interface. The code 
for the event handler is pretty straightforward and just passes con- 
trol down to the filling procedure. 


void CurrentChanged(Object sender, EventArgs e) 


{ 
RefreshList((CurrencyManager) sender); 


} 
The most interesting part of the code is in RefreshList. 


DataRowView drv = (DataRowView) cm.Current; 
DataRow row = drv.Row: 
DataRow [] rgChildRows = row.GetChildRows(m RelationName) ; 
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RetreshList takes an argument of type CurrencyManager. The Cur- 
rent property of this object evaluates to the data item object cur- 
rently selected in the master control. As I explained earlier, the 
CurrencyManager hides the details of the parent controls from the 
caller. Regardless of the type and number of the controls bound to 
the specified data source, CurrencyManager represents them all by 
supplying a common programming interface. The data item that 
the DetailListView control gets from the binding manager is an 
instance of the data object behind the user interface row displayed 
by the parent control. For example, if the parent control is a Data- 
Grid, then each displayed row is a DataGridItem object. Although 
the DataGridltem object represents a row in the grid, it has noth- 
ing whatsoever to do with the underlying data object that supplies 
the text shown in the cells. Each row in the DataGrid is bound to a 
data object and the collection of all the individual data objects 
forms the overall data source. 

Once the RefreshList method has retrieved the DataRow object 
for the currently selected parent row, it can finally exploit the exist- 
ing data relation. The DataRow’s GetChildRows method just re- 
turns an array of DataRow objects representing the child view. 
RefreshList extracts column information from these rows and then 
populates the ListView. 


Items.Clear(); 

foreach(DataRow r in rgChildRows) 

{ 
ListViewItem lvi = new ListViewlItem(); 
lvi. Text = r[0].ToString(); 
for(int i=l; i<dt.Columns.Count; i++) 

Ivi.SubItems.Add(r[i].ToString()); 
Items .Add(1vi); 
} 


Columns are dynamically added by looking at the structure of 
the table used to create the layout of child rows, as shown in Figure 
7. The code also automatically right-aligns the text for columns 
which contain numeric data. Figure 8 shows the final results. 


Information Drilidown 

A lot of applications use a two-step mechanism to show poten- 
tially lengthy and rich data. Typically, applications showa scrollable 
list of key fields—say, ID and last name—and then leave the user 
free to click rows and have the rest of the available information 
drilled down. Basically, two synchronized data controls share the 
same DataSet, but display a different set of columns. The Windows 
Forms data binding engine easily allows for this, as the next sample 
application demonstrates. 


Figure 7 Dynamically Adding Columns 
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[7 automatic Master Detail - Grid When youre finished configuring columns, you add the 
———— av, einen 
erplayees snare __[rstnane masterGrid.TableStyles .Add(gridStyle) ; 

Showing only a few columns out of the DataTable does 
not affect the automatic master/details capabilities of Win- 
dows Forms data binding. I wrote a row viewer control 
(called DataRowViewer) that displays the current values 
of all fields in the table. The DataRowViewer inherits from 
the ListView class. It features two columns, Name and Value, 
and adds as many rows as there are columns in the table. 
Aa Sn Ae een . The DataRowViewer control includes the standard piece 
4/15/1996 12:00:00 8M Des of code I discussed earlier, which makes it capable of de- 
tecting controls bound to the same data source. Thus it 
can automatically work as the child in a parent/child rela- 
tionship. I based the user interface of this control on the 


Fea r=) aie 0/000 cs eae eae shakes irae. 
3/12/1998 12-00-00 AM its eae am! ae List View control because I wanted it to work with any data 
3/11/1998 12-00-00 AM one 
DataRowViewer control as a form, making use of any com- 
Figure 8 The Final Result bination of child controls (TextBox, ComboBox, Check- 


sca Box) to view and edit the various data fields. Notice that 
The idea is to have a DataGrid show employee names and a new, 


custom control that binds to the selected row in the grid and dis- 
plays all the columns. The DataSet has only one table, which is 
filled by a very simple query command. 


String strCmd = "SELECT * FROM Employees”; 
SqlDataAdapter da; 

da = new SqiDataAdapter(strCmd, connString); 
DataSet ds = new DataSet(); 

da.Fill(ds, "Employees"); 


You bind the DataGrid to the data source with the same code that 


Figure 9 Customizing the DataGrid’s Style 


was shown earlier. 
masterGrid.DataSource = ds; 
masterGrid.DataMember = "Employees"; 


Unless you explicitly define some custom table and column 
styles, the DataGrid would simply mirror the contents of the table. 
To force it to show only a subset of the columns, configure the grid 
as shown in Figure 9. You first create a DataGridTableStyle object 
and map it to the name of the bindable DataSet table. Notice that 
the match is case-sensitive, so make sure that the value of 
MappingName exactly matches the name of the DataTable. At this 
time, you could also set some graphical styles that would override 
others set on the DataGrid control itself. These settings are specific 
to the table being displayed and are automatically reset when that 
table is detached from the grid. 

The second step requires you to create as many columns as 
needed. The .NET Framework provides only two types of col- 
umns, TextBox and Boolean, but supports custom columns you 
might want to write. 


DataGridTextBoxColumn coll; 
coll = new DataGridTextBoxColumn(); 


The grid column must be mapped to one of the table columns. 
You use the MappingName property and, again, watch for case- 
sensitivity. Each column has to be added to the GridColumnsStyles 
collection of the table-style object. 


coll.MappingName = "employeeid"; 
gridStyle.GridColumnStyles.Add(coll); 
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the DataRowViewer class has been built into the Visual Studio 
project as a true control, so you'll find it available from the toolbox 
as well. Figure 10 shows the controls in action in the sample app. 


DataGrid versus DataGrid 


The .NET Framework comes with two flavors of the DataGrid 
control, one for Windows Forms applications and one for Web 
Forms. Aside from the fact that they both provide grid functional- 
ity, the two controls are completely unrelated. They have distinct 
sets of features and capabilities, belong to different namespaces, 
and can be used in different models of applications. 

Automatic master/detail relationships are made possible by the 
data binding mechanism of Windows Forms applications where 
the BindingContext class plays a key role. 

Web controls do not have the notion of a binding context for a 
good reason. At the root of the master/details applications, there is 
a selection event. When this happens over the Web from within a 
typical ASP.NET application, there is a round-trip between the 
selection event and the subsequent page refresh. The binding con- 
text is invalidated and would need to rebuild each time the page is 
loaded. Although possible in theory, this could create useless over- 
head. Automatic master/detail relationships are still possible in 
Web Forms applications to some extent. However, it utilizes other 
classes and techniques, which means it will will make good fodder 
for next month’s column. 


On-the-fly HTML to PDF Conversion 
Almost 300 Document Types to PDF 
Appending, Stamping, Stitching, and Form-Filling 


www.activepdf.com 


Copyright © 2001, activePDF, Inc. 


1 Davolio 


Sleveing 


Employee! LD 
Last ame 
First) ame 
Title 

Title fCourtesy 
BirthD ate 
HireD ate 
Address 

City 

Region 
PostalCode 
Country 
HomePhone 
Extension 
Photo 

Notes 
ReportsTo 
PhotoPath 


Fuller 

Andrew 

Vice President, Sales 
Dir. 

2/19/1952 12:00:00 4M 
6141992 12:00:00 4M 
908 Wi Capital Way 
Tacoma 

willy 

96401 

USA, 

(206) 555-9482 

S457" 

System. Bute] 

Andrew received his BTS commercial in 1974 and a Ph.D. in international ... 


http: ‘accweb/emmployees,fuller. bmp 


Figure 10 DataRowViewer Control in Action 
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ike traditional C++, the Managed Extensions for 
C++ introduced with Visual C++" .NET allow you 
to go pretty much wherever you want to go within 
the confines of the underlying platform. This means 
that developers using Managed Extensions for C++ 
have a few more tools and options than program- 
mers working in other Microsoft’ .NET languages—but this power 
comes at a price. As with traditional C++ code, there is more 
complexity and a heavier syntactical burden for tasks that are of- 
ten easy in other languages. 

In this article ’m going to show you a number of techniques to 
make your work easier when you use the Managed Extensions for 
C++ to write applications for .NET. This article assumes you are 
already familiar with the managed C++ syntax and most of the 
basic principles, although I'll explain some constructs that might 
be more complex or unusual. 


Overloaded Implicit and Explicit Conversions 


The C# language allows developers to overload both implicit 
and explicit conversion operators via the implicit and explicit key- 
words. Consider this simple C# example: 


public class Convertible { 
private int _value; 
public Convertible ( int v ) { _value = v; } 


public static implicit operator int ( Convertible c ) { 
return c._value; 


} ed C:\Program Files\Microsoft. NET \Framework SDK ABin\wedl. exe tors can be split across two main cat- 


public static explicit operator double a > MANIFEST 


( Convertible c ) { &-W@ Microsoft DevApps.WebServices egonies. unary and binar y- Both catego- 


return (double)c._value; &Q§E AssemblyRet 


} 

The two overloaded operators shown 
in the previous code allow you to con- 
vert an instance of Convertible into a 
32-bit integer value without an explicit 
cast, or convert it to a 64-bit floating- 
point value with an explicit cast. 

Now, consider how youd invoke any 
of these conversion operators from a 
managed C++ client. The first thought 
that comes to mind is just doing the 
same thing a C# client would do: 


C 
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Convertible* c = new Convertible(15); 
int cl = *c; 
double c2 = (double)(*c); 


However, that doesn't work, and you'll 
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System anagement : static assembly literal string static bool op_<name>(MT* 0); 
SystemMMessaging : static assembly literal string t § 
SystemAuntimeRemoting : static assembly literal string and for binary Oper ators, the signatures 


SpstemAuntimes erializationFormattersS oap : static assembly li are the following: 


static MT* op_<name>(MT* Ths, MT2* rhs); 
static bool op_<name>(MT* Ihs, MT2* rhs); 


Please note that I use MT and MT2 as 


see a couple of C2664 errors if youtry Figure 1 The IL Disassembler placeholders (think of a template syn- 


to compile it. So, how do you do it? 

The trick lies in figuring out what code the C# compiler gener- 
ates behind the scenes for these two conversion operators. Fortu- 
nately, the .NET disassembler, ILDASM.EXE, can tell you (see 
Figure 1). ‘This is how those two operators are defined in intermedi- 
ate language (IL): 


// implicit operator int 
.method public hidebysig specialname static 
int32 op_Implicit(class Convertible c) cil managed 
{ 
} 
// explicit operator double 
.method public hidebysig specialname static 
float64 op_Explicit(class Convertible c) cil managed 
{ 
} 


As you can see, what you really have here are two methods, op_ 
Implicit and op_Explicit, marked with special attributes so that 
they are usually hidden from the user. The C# compiler uses syn- 
tactic sugar so that these methods are invoked implicitly in a stan- 
dard-defined conversion sequence, or explicitly in a cast expression. 
So actually youre not dealing with C++-style operators at all. 

What you can do, however, is call these methods directly from 
managed C++ to accomplish what you want. Here’s what the new 
code looks like: 


Convertible* c = new Convertible(15); 
int cl = Convertible::op_Implicit(c); 
double c2 = Convertible: :op_Explicit(c); 


You can use this same technique to write managed classes in C++ 
that overload conversion operators usable from C#. Then you can 
add static op_Implicit and op_Explicit methods to your __ gc or 
__value classes and have them turn up in C# as overloaded con- 
version methods. 


Overloading Operators 

Most other operators can be overloaded using a technique simi- 
lar to the one used for implicit/explicit conversion operators, from 
C# as well as from the Managed Extensions for C++. The opera- 


tax) for managed types in these signa- 
tures, where MT2 and MT might be the same type. 
Most of these operators, except for op_True and op_False, will 


Figure 2 Overloadable .NET Operators 
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be recognized by C++ developers who are familiar with operator 
overloading. Basically, these two operators allow a class to be evalu- 
ated as a Boolean expression and thus participate in more complex 
Boolean expressions, like using the logical AND/OR/XOR opera- 
tors. They can also be used as condition variables in conditional 
statements such as if or while. This is something developers can 
accomplish to a certain degree in traditional C++ by providing 


implicit conversions to bool. It is also worth noting that, in most | 


contexts, the same holds true for C# code. 

So what do op_True and op_False really do? They become re- 
ally useful when you have types that have to deal with poly-valued 
logic, and thus can be thought to be, logically speaking, in true and 
false states at the same time, or in neither state. The classic example 
in the framework where you'll see this is the SQL data types in 
System::Data::Sql Types, which implement equality and inequality 
operators in terms of the 
SQLBoolean value type. 
SQLBoolean implements 
op_True and op_False in- 
stead of an implicit con- 
version to bool, which 
allows it to work correctly 
when null database values 
are involved. (If a SQL- 
Boolean value is null, then 
both op_True and op_ 
False will return false. ) 

Looking at it from an 
implementation standpoint, it’s interesting to note that, as in C#, 
all operators are overloaded by implementing these functions as 
public static members of a managed class. This is unlike tradi- 
tional C++ code, in which some have to be implemented as mem- 
ber functions while others are implemented as global functions. 

Asa return type, almost all operators have the same type as the 
class they are defined in. So if you implement a class called My- 
ManagedClass, then that’s the type the operators should return. 
The only exceptions are those operators marked with an asterisk 
(*) in Figure 2, which usually return a Boolean value instead. 

Here’s a short example of how you'd implement a unary .NET 
operator such as op_Increment: 


__gc class IntWrapper { 

private: int m_value; 

public: 
IntWrapper(int v) : m-value(v) { } 
__property int get_Value() { return m_value; } 
__property void set_Value(int v) { m_value = v; } 


static IntWrapper* op_Increment(IntWrapper* 0) { 
return new IntWrapper(o->Valuet1) ; 
} 
it 


Implementing a binary operator for IntWrapper, such as op_ 
Addition, would look such as this: 


static IntWrapper* op_Addition(IntWrapper* lhs, IntWrapper* rhs) { 
return new IntWrapper(1hs->Value + rhs->Value); 
} 


Since overloaded operators are not in the Common Language 
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Specification (CLS), you should always provide alternative meth- 
ods in your classes that implement the same functionality as those 
operators. This allows them to be consumed by other languages 
such as Visual Basic’ .NET, which dont support operator over- 
loading. This can also be much more convenient in terms of the 
Managed Extensions for C++ since most .NET operators are not 
easily consumed from managed C++ code without calling the 
op_XXXX methods directly. In other words, this won't compile: 

IntWrapper* v(1); 

IntWrapper* z(1); 

IntWrapper* y =v + Z; 

This is a side effect of using explicit pointer notation for han- 
dling references to managed objects in managed C++ because 
arithmetic operators have a special meaning when they are com- 
bined with pointer semantics, even if those semantics are prohib- 
ited in managed code. 

However, if youre defining value types using the __value key- 
word, remember that your overloaded operators wont use point- 
ers as arguments or return values, but as complete value types. 
Also note that the .NET overloaded operators can be consumed 
from managed C++ directly without needing to go through the 
op_XXXX methods, since pointer notation doesnt get in the way 
in these cases. 


Handling Managed Types from Unmanaged Code 
One of the problems youre bound to get yourself into when 

mixing managed and unmanaged code is that unmanaged C++ 

cannot touch a managed type instance directly. The simplest 


- workaround is to use a set of standalone managed functions that 


can be called from the unmanaged code. While this technique is 
simple and useful, it falls short in many cases, particularly those in 
which you need to hold the managed object and manipulate it over 
longer periods of time. 

What you need is a way to hold the managed object in some 
location that can be called from unmanaged code. The first thing 
that comes to mind is an unmanaged type with managed meth- 
ods—that is,a__nogc class in a managed code section. However, 
the unmanaged type cannot hold the managed instance directly, 
since the .NET runtime is not completely aware of unmanaged 
types and the garbage collector (GC) has no way to keep track of 
the references to the managed types that way. 

Fortunately, there is a way to accomplish this with just a tad 
more work. The solution is to use the GCHandle structure found 
in the System.Runtime.InteropServices namespace of the .NET 
Framework. This structure gives you a means to hold a managed 
object reference in unmanaged memory. One of the nicest things 
about GCHandle is that it allows you to keep all types of refer- 
ences, including pinned and weak references. 

Using GCHandle is fairly simple. You use the GCHandle::Alloc 
method to create an opaque handle to a managed object and GC- 
Handle::Free to release it. Also, the GCHandle::Target method al- 
lows you to obtain the object reference back from the handle in 
managed code. Figure 3 shows you how to create a simple wrapper 
class around the current AppDomain object. It’s not hard, as you 


can see, but it’s a little bit annoying, particularly when you have to 
cast constantly to get at the object reference. If you're wondering 
about GCHandle::op_Explicit, it’s simply a way to trigger the ex- 
plicit conversions operators defined in GCHandle that allows a 
GCHandle instance to be cast to and from an IntPtr, which is the 
.NET runtime version of a native-size pointer. 

The good news is that you don’t have to do this if you use a little 
template tucked away in gcroot.h called, well, gcroot. This is basi- 
cally a smart pointer around a GCHandle instance. I rewrote the 
code from Figure 3 to use gcroot instead of GCHandle directly, as 
you can see in Figure 4. 

Like any other smart pointer, gcroot overloads operator->, al- 
lowing you to use it directly without casting. It does a good job of 
abstracting away the details of calling IntPtr::ToInt32 or IntPtr:: 
ToInt64, depending on which platform the executable was com- 
piled for (Win32° or Win64"). 

You should be using at least the release candidate version of 
Visual Studio” .NET by now, but be aware that although the com- 
piler would allow you to simply hold a GCHandle instance inside 
AppDomainWrapper (and it would mostly work), you might run 
into unexpected crashes with the Beta 2 compiler, since it has a bug 
that causes it to get the size wrong. 


Unboxing 

Unlike in C#, boxing operations are explicit in managed C++, 
so you have to use the __box keyword when boxing a value type. 
However, you wont find any ___unbox keyword, so how do you get 
the value type back? You can do it with a dynamic_cast, like this: 


int a = 12432; 
System: :0bject* 0 = __box(a): 
std::cout << "original value: " << *(dynamic_cast<System: :Int32*>(0)): 


Ugly, isn't it? Besides all the trouble it involves, there’s also the 
small problem that dynamic_cast won't accept an unmanaged type, 
like an int*. Instead you have to use the managed value type coun- 
terpart in the System namespace (Int32, in this case), unless you 
use the even less intuitive alternative: 


*(dynamic_cast<__box int*>(0)); 


Unboxing requires a deep understanding of boxed types. You must 
first cast the Object* to a pointer to the boxed version of the type 
you want (for example, __box int*), and then you can dereference 
that pointer, yielding an object of the unboxed type. Fortunately, 
you can wrap this process in a simple unbox template, which yields 
the object directly. It costs a little more since it is passing value 
types by value, as opposed to boxing them by reference, but it is 
simpler. If youre like me, and want consistency and simplicity, 
then you long for an unbox function that you can use to make this 
easier. It turns out that its pretty easy to simulate with the following 
template function: 


template <typename U> 

inline U unbox(System: :0bject* o) { 
return *(dynamic_cast< box U*>(0)); 

} 


which can now be used like this: 


std::cout << “original value: " << unbox<int>(o); 


That’s much more readable. However, a few matters still need to 


be addressed. The first one is that the method I’ve just presented 
wont work in Visual Studio” .NET Beta 2 if the value type youre 
unboxing isa managed Enum. This is a compiler bug, which means 
youll get an internal compiler error when the compiler reaches the 
dynamic_cast in unbox. 


Unfortunately, there’s no easy way around this problem short of 
changing unbox so that it uses static_cast instead. This requires 
checking that the type conversion is valid before making the cast, 
like this: 

template <typename U> 

inline U unbox(System: :0bject* 

if ( __typeof(U)->Equals(o->GetType()) ) 


return *(static_cast<U _ box*>(o)); 
throw new System::InvalidCastException(); 


pian 


} 
If youre dealing with boxed enum types, then this last attempt 
wont compile if you're using System::Enum __gc* variables. For 
example, if you try this 


value enum TheEnum { 
vall, 
val2, 
val3, 

i 


System::Enum __gc* pa = __box(TheEnum::val1); 
youll get the following error: 
: error C2594: : ambiguous conversions from 


mepptt.cpp(100) ‘argument’ 


"System: : 
Enum gc *' to ‘System: :Object 


ae 

What’s ambiguous in this conversion? Well, nothing, really. You've 
just run into a bug in Beta 
2 of the Visual C++ .NET 
compiler, which has prob- 
lems dealing with the im- 
plicit conversion between 
System::Enum* and Sys- 
tem::Object*. If youre still 
not using a later version of 
the compiler, the only 
workaround that can be 
used is to overload the un- 
box function with a ver- 
sion explicitly taking an 
Enum* argument, which would look like this: 


template <typename U> 
inline U unbox(System::Enum* 0); 


This last definition of unbox would have the exact same imple- 
mentation code as the one taking a System::Object* argument that 
I presented before and will allow the sample code to compile. 

Ona related note, it’s interesting to see that when youre dealing 
with value types, there’ a big difference between the following two 
lines of code: 


TheEnum 
TheEnum __gc* pa = 


__box* pa = __box(TheEnum::val1); 
__box(TheEnum: :val1); 


The first line of code declares a boxed value type. This is essentially 
_a way to treat the boxed value as if you were dealing with a refer- 
ence type without needing to unbox it every time you have to 
access any of its members. (This happens implicitly in some other 
.NET languages.) 

The second line of code declares an interior __gc pointer that 
points directly at the value stored inside the boxing object. Interior 
pointers have several important restrictions and special semantics 
and can be hard to deal with, so I suggest you avoid them unless 
absolutely necessary. 
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Keep the first definition of unbox handy, though. That's the one 
youll want to use once the bugs in the compiler are worked out. 


Converting Managed Strings to Character Arrays 

Having to convert managed strings to character arrays is quite 
common when you need to call unmanaged functions that handle 
strings. As it turns out, there are several ways to accomplish this. 

The first option is to use the StringloXXXX methods of the 
System::Runtime::InteropServices::Marshal class. There are varia- 
tions for each combination: ANSI strings, Unicode strings, BSTRs, 
and so on. Here’s how youd use it to get a const char* out of a 
String instance: 


using namespace System: :Runtime: 

const char* str = (const char*) 
(Marshal::StringToHGlobalAnsi(managedString)).ToPointer(); 

// use str as you wish or copy it elsewhere 

// free string 

Marshal::FreeHGlobal(IntPtr((void*)str)); 


:InteropServices; 


The StringToXXX methods return an IntPtr instance, so you need 
to convert that either to a pointer or an integer value (32 or 64-bit) 


| before using it. Don't forget to use the appropriate Marshal::Free- 


XXX methods when youre finished in order to release the allo- 
cated memory. 

The second option is to use PtrToStringChars. PtrToStringChars 
allows you to get access to the internal memory representation 
of the managed string instance with a simple function call. The 
veclr.h header file (which is available in the Visual C++ .NET 
installation) contains the definition and the source code im- 
plementation of PtrToStringChars so you can see how it is done. 
Here's a short example: 

const System::Char* str = PtrToStringChars(managedString) ; 


The downside of this option is that the pointer returned is a___gc 
pointer, which you can see more clearly by using this alternative 
definition of str: 


const wchar_t __gc* str = PtrToStringChars(managedString) ; 


While the previous option is certainly simpler, it suffers from 
two drawbacks. The first one is, of course, that it returns a man- 
aged pointer (actually, it is technically called an interior gc pointer, 
and you should make sure you don't accidentally end up writing 


_ through it or you might corrupt the managed heap). The second 


drawback is that it returns a Unicode string, so you might need yet 
another conversion if you need an ANSI string. 

There is a way to convert the __gc pointer to a__nogc one, but 
that’s only possible if you pin it in memory so that you can make 
sure that the string instance won't be moved during the garbage 
collection cycles, as shown here: 


const wchar_t __pin* str = PtrToStringChars(managedString) ; 


The downside of this is a potential performance hit, since pinned 
objects can cause sandbars in the managed heap, preventing a full- 
heap compaction from being performed. If you plan to use pinned 
objects, use them sparingly and never hold onto them for long 
periods of time. 


Converting String to std::string 


The C++ standard library std::string and std::wstring are string 


Figure 5 Marshaling Strings 


management classes that many people (myself included) use ex- 
tensively so it’s nice to have a way to convert a System::String in- 
stance into either std::string or std::wstring. Figure 5 shows two 
simple functions to convert a System::String* into a std::string or 
std::wstring instance. If you prefer to have these functions return 
the unmanaged string instance instead of passing it as a reference, 
it is easy to do so. Note that overloading won't work in that case and 
youll need to give different names to each function. 


Mixing Templates and Managed Types 

The .NET platform doesn't support generic programming yet, 
but managed C++ programmers can still take advantage of the 
template mechanisms available in normal C++ to a certain extent. 
Of course, this means you can only use them as internal aids to 
your managed C++ implementation and cannot expose them to 
other .NET languages, but they are still useful for a few tricks. 


Figure 6 auto_dispose Template 
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You've already seen two examples of mixing templates and man- 
aged types in the form of the gcroot template and the __unbox 
function. Now Ill tell you about a few other tricks you can put in 
your bag. 


Is Operator for Managed C++ 

The C# language has an is operator that allows you to easily find 
out if an object has a given managed type, implements a given 
interface, or is in the same inheritance hierarchy as another type. 
The is operator simplifies some expressions and is exception-free, 
so it’s quite useful. I wanted a way to simulate it, at least partially, in 
managed C++. 

My first attempt was to create a templated function that com- 
pared types: | 


template <typename Tl, typename 12> 
inline bool istypeof ( T2* t ) 


{ 
return ( __typeof(T1)->Equals(t->GetType()) ); 
} 


Obviously, this only accomplishes the goal of identifying the type, 
so I needed to extend it a little bit more. I turned to dynamic_cast, 
which behaves pretty much in the way youd want. Here's the sec- 
ond attempt: 


template <typename Tl, typename 12> 
inline bool istypeof ( T2* t ) 


{ 


return (dynamic_cast<T1*>(t) != 0); 


} 


This is much better and works almost like youd expect. Here's how 
youd typically use it: 

bool isaB = istypeof<B>(someObject) ; 

However, there’s one shortcoming: you cant pass a native type as 
T1 and expect it to work correctly. In other words, if you try some- 
thing like this 

bool isanInt = istypeof<int>(someObject) ; 
youll get a C2682 compiler error. Trying System::Int32 instead of 
int doesn't work either. The solution is to compare the object's type 
to the boxed value type, instead of a pointer to the raw type. How- 


ever, this requires using the __box syntax like so: 
bool isanInt = istypeof<int __box>(someBoxedInt) ; 


This is certainly awkward and unintuitive, but unfortunately can-: 
not be worked around (at least I haven't found a suitable 
workaround; if you do, please tell me!). 

One thing to watch out for when using the __ typeof operator in 
managed C++ is that __typeof(wchar_t) can return different val- 
ues depending on the compilation options. With the default com- 
piler flags, it will return __typeof(System::UInt16), since the 
compiler doesn't enable wchar_tas an intrinsic type by default and 
instead defines it as unsigned short. However, if you compile with 
the /Zc:wchar_t compliance switch, it will return __typeof(Sys- 
tem::Char), which is what youd expect. 


Simulating C#’s using Statement for 
IDisposable-aware Objects 

This technique is rather easy to simulate using a simple template 
class, similar in behavior to gcroot, which I’ve called auto_dispose 


(see Figure 6). Using auto_dispose is a little different from using 
gcroot in the sense that the auto_dispose definition is similar to 
that of std::auto_ptr in the Standard C++ Library. With auto_dis- 
pose, you dont specify pointer syntax when declaring the man- 
aged object type, as you do with gcroot. This is merely a matter of 
personal preference since I feel more comfortable with auto_ptr’s 
syntax than with that of gcroot, but modifying the auto_dispose 
definition to turn it around is quite simple. Here’s how you would 
use auto_dispose: 


auto_dispose<DisposableObject> obj = new DisposableObject; 
// use obj as any other managed object pointer 


// obj->Dispose() called automatically at end of scope 


There are a couple of points worth mentioning about the imple- 
mentation of auto_dispose. The first is that the implementation of 
the destructor uses static_cast to ensure that the type T does in- 
deed implement IDisposable. (I’m not interested in the general 
case where a random class implements a Dispose method different 
from [Disposable::Dispose.) This is necessary because standard 
C++ template syntax provides no clean way to specify static type 
requirements. For example, there's no precise way of specifying 
that a template argument should implement a given interface or be 
derived from a certain base class. Using static_cast here allows you 
to work around this problem (at least partially) to get a compile- 
time error if T doesn’t implement IDispose. 

Second, note that auto_dispose hides its copy constructors and 
assignment operators, which is done to avoid easy copying of the 
inner pointer into another auto_dispose instance. This is really 
important because if it were allowed, situations could arise in which 
IDisposable::Dispose could be called twice, at different times in 
the same object, which is not what you want, of course. 

Third, you don't want to get direct access to the inner pointer 
held by auto_dispose, which is why there is no implicit conversion 
operator to T* defined in the template, unless you need to pass 


down the object as an argument to another function. In most cases 
this is a dangerous and error-prone thing to do, because it forces 
you to treat the function you are calling as a white box, thus break- 
ing the encapsulation. 

To see why this occurs, consider the case in which the function 
you just called with the disposable object caches the object in- 
stance somewhere, and | 
you call Dispose shortly 
thereafter. The function 
now has what essentially 
amounts to a reference to a 
dead object, possibly in an 
invalid state (even though 
the GC doesn't consider it 
dead yet), which might 
cause unexpected prob- 
lems later on. This can 
make your code throw un- 
expected exceptions and 
presents a situation that is difficult to debug. Finally, notice that 
you could still get the inner pointer by calling auto_dis- 
pose::operator->() directly if youre persistent, although you should 
really try to refrain from doing this. 


Conclusion 

As you can see, managed C++ is quite flexible and can do as 
much as any other .NET language can do, although sometimes it 
takes more effort on your part to make things happen. Fortunately, 
with a few handy routines and some tips and tricks up your sleeve, 
you can be much more productive in Managed Extensions for 
C++ and make your code more readable and maintainable. 


Tomas Restrepo is a software developer at InterGrupo S.A. and is interested in object-oriented 
programming, design patterns, and C++. You can reach him at tomasr@mvps.org. 
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Notenboom 


This article assumes you're familiar with C#, Visual Basic .NET, and the CLR 
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f you've started using Microsoft’ Visual Studio” .NET 
you know it is packed with new features and tech- 
nology. While you may think of the integrated devel- 
opment environment (IDE) as simply a text editor 
for writing code, it's really much more. It provides 
the framework that the rest of the development tools 
plug into, offering a single, seamless, development experience. Of 
course, it can't be all things to all people; functions you or I find 
useful might not be there. Fortunately the IDE has been equipped 
with extensibility features that allow extensive customization of 
Visual Studio .NET to meet just about any need. 

In 1988 I wrote an article for Microsoft Systems Journal entitled 
“Customizing the Features of the M Editor Using Macros and C 
Extensions.’ That article discussed the macro language unique to 
the M editor, as well as the approach developers could use to ex- 
tend the editor by writing code in C. Fortunately, in the years since, 
macros and macro recording have converged on a more common 
mechanism and language. Extending the IDE via compiled code, 
however, remains a powerful, albeit complex, method for modify- 
ing the coding environment. 

In this article P'll describe an add-in I developed for Visual Stu- 
dio .NET that implements several new text editing functions. In 
detailing some of the steps involved, you'll see how add-ins inter- 
face with the IDE’s automation model. 

Note that the Visual Studio .NET macro recorder uses Visual 
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Application Center Test Projects 


Figure 1 Creating a New Project 


Basic’ .NET by default. Visual Basic isn’t a requirement and to 
prove the point, I'll use C#. Like Visual Basic .NET, C# also runs in 
the .NET Framework managed environment, providing a secure 
setting for building add-ins. 


Getting Started 


Both add-ins and macros can be used to extend the IDE in a 
number of ways. Macros are recordable and can be run immediately. 
Therefore, they are a great way to explore the object model. Macros 
are distributed as a single -vsmacros file, and are loaded into the 
macro editor simply by double-clicking that file. Since macros are 
available in source form, they can easily be modified by the user. 

Add-ins, on the other hand, are compiled and thus cannot be 
modified once distributed. This protects your intellectual prop- 
erty. With add-ins, you can create tool windows that operate just 
like those native to Visual Studio .NET. Add-ins can dynamically 
alter the state of the commands on menus and the. soli acgtaial bar 
and even add information to the Help About box. Since 
add-ins can be distributed as single Microsoft Installer 
(.MSI) files, they can be easily installed and uninstalled 
through the standard Control Panel Add/Remove Pro- 
erams applet dialog. 

The steps to create an add-in are covered in the Visual 
Studio .NET online help, as well as on the Visual Studio 
.NET Automation Examples Web site (http://msdn.micro- 
soft.com/vstudio/nextgen/automation.asp). I won't go through ev- 
ery step in detail here, but will review some of the choices | 
made to create the add-in. 

To create an add-in, you start by creating a new project. 
Underneath Other Projects in the New Projects dialog, 
youll find Extensibility Projects. From there, select Visual 
Studio .NET Add-in. Figure 1 shows the New Project dialog 
at this point. Press OK and the add-in wizard will start. 

For my add-in, the first three pages of the wizard are 
quite straightforward. On Page 1, I selected C# as the pro- 
eramming language for the add-in. On Page 2, k chose 


Microsoft Visual Studio .NET as the application host. This 

is where the editing functions that Ill present here make 

the most sense. You can, of course, include the VSMacros 

IDE for editing functions of your own design. On Page 3, I 

named the add-in “Text Editing Utilities,” and provided an 

appropriate description. 

Page 4 of the wizard, which is shown in Figure 2, provides 
you with several options. 

- Check “Yes, Create a “Tools’ menu item.” This option 
also enables editing command processing in your add- 
in, even if you use no UI. 

* Leave “My Add-in will never put up modal UI...” 
unchecked. The example I provide here will not put 
up a UI, but it's quite possible that you'll want to further 
extend your add-in to do so. 

- Leave “I would like my Add-in to load when the host 
application starts” unchecked for now. This will make 
debugging a little easier. The user of your add-in can 

change this option in the Add-in Manager later. 

* Ichecked“My Add-in should be available to all users ... °° This 
is optional. On my machine I'm really the only user, as 'm 
sure is the case for most developers. This option just changes 
which registry hive the add-in is registered in. 

On Page 5 of the wizard, you can include some Help About 
information. Check the checkbox and enter whatever contact in- 
formation is appropriate for you. And now, courtesy of the New 
Project Wizard, you have the beginnings of your add-in. 

The following methods in the Connect object are the work- 
horses of the add-in and can be found in connect.cs, which is now 
part of your new project. 

* Connect::Connect. This constructor is where you'll put your 
simple initialization. 

- Connect::OnConnection. This method is called when the IDE 
actually loads the add-in you've created. This is where youll 
initialize your add-in, inform the IDE of the commands you 


‘Choose Add-in Options. 
Add-in Options 


Figure 2 Add-in Wizard 
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have to offer, assign keyboard bindings, and so on. 

* Connect::QueryStatus. This method is called by the IDE to 
determine whether or not a command is appropriate in the 
current state. 

* Connect::Exec. This method is called by the IDE to actually 
execute commands. 

Now that all the basics are in place, let's look at the development 
of a simple example of an add-in. 


A Simple Editing Function: InsertDate 

I created a simple command, InsertDate, that does exactly that: 
it inserts the current date at the current cursor location or in place 
of the currently selected text. There is already a sample macro 
included with Visual Studio .NET that does this, so you'll be able to 
see this same functionality implemented as both a macro and as an 
add-in. It is so simple that you only need to modify one of the 
functions listed earlier, the Exec function. 

The basic add-in I created, according to the steps in the previous 
section, implements a command called TextUtil, or more correctly, 
TextUtil.Connect.TextUtil. In the Exec function, I replaced the 
wizard-generated line 

handled = true; 
with 

handled = InsertDate(); 
and added the following InsertDate method, which can be added 
anywhere within the Connect object: 


// InsertDate 
// Insert the current date in my favorite format. 
Lh 
bool InsertDate() 
{ 
if (null != applicationObject.ActiveDocument ) 
((TextSelection)applicationObject.ActiveDocument.Selection).Text 
= DateTime.Now. ToString("dd-MMM-yyyy"™); 
return true; 
} 


The InsertDate function does the work, using the System. Date- 
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_ Time and System.String objects. See the sidebar “Strings in C#” for 
| a quick introduction to System.String. At this point I commented 
| out the three lines of code in OnConnection which reference Com- 
| mandBars. These lines create the Tools menu items, which I'll re- 
| turn to later. 


Except for the name, the add-in is complete. To try it out, press | 


_ 5 to run it. A new instance of the IDE runs and in that instance, 
| the add-in will be listed in the Tools | Add-in Manager dialog. To 
| load it, check the far left checkbox in the Tools | Add-in Manager to 
| select itand press OK. Now you can open any text document, enter 


*TextUtil. Command.TextUtil” in the Visual Studio .NET com- 
mand window, and the current date will be inserted into the text 
document. In fact, auto-complete will fill out that command be- 
fore you've finished entering it. 

When you press F5, youre running both a new instance of the 
IDE and your add-in in the debugger. I’ve found it both informa- 
tive and useful when running in the debugger to break on all ex- 
ceptions, at least initially. In the normal course of events there are 
few, if any, exceptions. When there are exceptions, they can be 
easily disabled. More importantly, failures are much easier to de- 
tect if you get a chance to examine the exception information as 
soon as possible. 


Changing the Name of the Command 

The wizard assigned the command a default name (TextUtil). 
Since that’s not particularly descriptive and since I'll be adding 
more commands in a moment, I am going to change the name. 
Also, because I encountered some confusion when I inadvertently 
changed the case of a command name, I'll make the name com- 
parison case-insensitive at the same time. A case-insensitive com- 
pare is currently all that's needed to avoid that confusion. 

The first change that I'll make is to the AddNamedCommand 
call in OnConnection: | 


Command command = commands .AddNamedCommand(addInInstance, 
"InsertDate", 
"Insert current date ", 
"Inserts the current date", 
true, 59, ref contextGUIDS, 
(int) vsCommandStatus.vsCommandStatusSupported 
+(int)vsCommandStatus.vsCommandStatusEnabled) ; 


In QueryStatus, make the following change: 


if (commandName. ToLower( ) "textutil.connect.insertdate”) 


Next, in Exec I made a similar change: 


if(commandName.ToLower() == "textutil.connect.insertdate") 


The wizard preloaded the registry for the initial run, but the 
name change affects the registry information. This means that in 
addition to rebuilding the add-in, I need to rebuild the setup project 
and reinstall the add-in before these changes will take effect. After 
rebuilding the add-in, I just right-clicked on the setup project and 
selected Build. Then I right-clicked on it once again, and selected 
Install. (As I indicated in the comments that are included in the 
wizard-generated code, there are other options besides building 
the setup project; however, youll need it later, so I recommend you 
go that route from the start.) 

Now the command TextUtil.Connect.InsertDate will do what I 


want it to, as shown in Figure 3. But how 
does it do it? Let's look next at whats go- 
ing on behind the scenes for what I’ve 
created so far. 


What Makes the Add-in Work? 

The code for InsertDate that I showed 
you in the previous section is fairly 
simple, but it does make use of the auto- 
mation objects that at this point prob- 
ably seem somewhat magical. 

Pll start by saying that the Object 
Browser is your friend because it makes 
it easy to learn about the objects. In Vi- 
sual Studio .NET, you can simply right- 
click on any of the objects discussed, and 
select Go To Definition for a quick list of 
members. In the resulting window, 
shown in Figure 4, you can select any of the members and youll get 
a prototype with clickable types that will let you drill down even 
further. Or you can select any of the members and press F1 to go to 
the associated online help topic. 

The applicationObject represents the application in which the 
add-in is hosted, in this case the Visual Studio .NET IDE. It's passed 
to the add-in in the OnConnection method. You'll find “DTE” in 
the online help, even though applicationObject’s type used in the 
wizard generated code is “_DTE”. Youll see it has a number of 
interesting members that apply at the application level. 

One of those members is the Active Document property, which 
represents the document that currently has focus. That is the 
document you'll want InsertDate to operate on. Since window 
focus and document focus are related but not identical, a good rule 
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Figure 3 Running the Macro 
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of thumb is that the document with fo- 
cus is the one that would be saved by a 
File | Save, regardless of which window 
has the focus. 

The ActiveDocument.Selection prop- 
erty returns an object that represents the 
current selection in the document. Be- 
cause it's a generic object in C#, I cast it 
to a TextSelection. ActiveDocument is 
generic because the document is not nec- 
essarily text-based, such as a forms de- 
signer document. As a result, the 
Selection property is also generic, and I 
cast it to the TextSelection that the code 
actually operates on. 

TextSelection represents a view on a 
file that behaves in accordance with the 
Tools | Options settings and user state. 
It exposes the various properties and methods you might want to 
use to modify the file, and it can affect the user's view, the current 
selection, and the insertion point. If you've ever recorded a macro, 
you'll see that TextSelection was used to capture your activity. 

InsertDate simply sets the Text property to be the string with the 
current date. This behaves as if the text assigned was being typed. 
This means that any existing selection is replaced, or if there was 
no selection, then the text is placed at the insertion point, paying 
attention to the current insert/overtype mode. 

A different approach is to use the Insert method. This method 
allows you to control text placement and always represents a single 
undoable action. To use this method, replace the Text property 
assignment with the following: 


((TextSelection)applicationObject .ActiveDocument.Selection).Insert ( 
DateTime.Now. ToString("dd-MMM-yyyy"), 
(int) EnvDTE.vsInsertFlags.vsInsertFlagsCol lapseToEnd 
yi 


The vsInsertFlags parameter indicates ex- 
actly how the text is to be inserted and where 
the insertion point should be afterwards. 
Documentation for vsInsertFlags was inad- 
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vertently omitted from the online help, so I 
have included it in Figure 5. In this case, | 
want InsertDate to operate like a typed char- 
acter so that the user can just keep typing 
afterwards. That means vsInsertFlagsCol- 
lapseToEnd is the choice. 

Now that you understand how the add- 
in works, let’s make it easier to use by assign- 
ing a key combination to the command and 
adding it toa menu. 


Hooking Command Up to the 
Keyboard and Menus 

Using the command window in Visual 
Studio .NET to execute the function is 
handy, but not really practical for an editing 
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function you plan to use often. The good news is that the add-in 
can provide a default keyboard binding. 

Since youll be adding more functions later, let's take this oppor- 
tunity to clean up the code a little by creating a support function 
that wraps the AddNamedCommand call and hooks up the key- 
board binding. This function, AddCommand (see Figure 6), takes 
as parameters only those settings, such as the command name, 
tooltip text, and so on that are actually different for each command 
added, and provides appropriate defaults for everything else. The 
code in OnConnect now changes to the following, and AddCom- 
mand does all the heavy lifting. 


AddCommand ("InsertDate", "Insert Date", "Inserts the current date", 
« “Ghopakesaltehoal thd’; “Edit ): 


If a nonempty string is passed as the fourth argument to 
AddCommand, it makes the keyboard assignment by first attempt- 
ing to retrieve the array of current key bindings from the newly 
added command. If there already are key bindings, then it assumes 
that the user has further customized their settings and won't at- 
tempt to replace them. Otherwise it creates the binding array con- 
sisting of a single binding, and then assigns that back to the 
command object. 

As I found from experience, the key binding assignment throws 
an exception unless youve created a non-default keyboard map- 
ping scheme. The default scheme cannot be modified, and of course 
that’s exactly what this code is trying to do. In Tools | Options | 
Environment | Keyboard, just click the Save As button and give the 
current keyboard mapping scheme a name of your own, and youl 
be able to modify at will. 

If you run the add-in now, you'll see that the two-keystroke 
sequence Alt+L, Alt+D will now insert the current date at the 
current cursor location in the current text file. 


Figure 5 vsinsertFlags Values 
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Attaching the add-in to the menu tree is similarly easy. 've added 
a fifth parameter to the AddCommand method, and if it is 
nonempty, the following code is executed: 

CommandBar commandBar = 

(CommandBar )applicationObject.CommandBars[szMenuToAddTo]; 

cmd.AddControl(commandBar, commandBar.Controls.Count) ; 
This associates the CommandBar object with the named menu 
and then adds the Insert Date command to the end of it. 


effort to go to just to insert the current date. Next I'll show you a 
few more of the objects that allow more complex interactions with 
the text and then use those objects to create something more use- 
ful: the text rewrapping function called Justify. 


Objects Used to Access Text 


So far ’'ve mentioned the DTE, ActiveDocument and TextSe- 
lection objects. DTE, of course, represents the application in which 
your add-in is operating. There can be only one, and it's provided 
when the OnConnection method is called. Document objects rep- 
resent documents currently open. The ActiveDocument property 
returns such an object, the currently active document, whatever it 
might be. You can access all the open documents via the DTE.Doc- 
uments collection. 

A TextSelection object represents text in an open document that 
has the selection. Not only does it contain the current state of a 
selection, but it also provides the mechanisms for modifying both 
the contents and location of the selection. Operating on a text 
selection is equivalent to a user editing a document; current user 
preferences, such as insert/overtype, or virtual spaces, are respected. 

There are some interesting objects that I haven't mentioned yet, 
such as Window, TextWindow, TextPane, EditPoint, TextPoint, and 
TextDocument. Next, I'll briefly explain their relationships and 
how they can be used when writing text manipulation functions. 

Window objects each represent a window in the IDE. The Text- 
Window object represents a window that's open in the application 
and which contains an editable text file. Much like the DTE.Docu- 
ments collection and ActiveDocument, TextWindow objects can 
be retrieved from DTE. Windows and ActiveWindow. A document 
can appear in more than one window. In fact, there is a Windows 
collection in each Document object, and each Window object that 
is a TextWindow contains a Document object. TextWindows also 
contain TextPane objects, which control how multiple panes within 
the window are displayed. 


So far the discussions have centered on the TextSelection object | 


as the primary editing mechanism. As I’ve said, it’s affected by user 
state and user-selected options, so operations are not necessarily 
deterministic. For example, a function that inserts text for one 
person may overwrite for another. 

Enter the EditPoint and TextPoint objects. These objects, which 
you can retrieve from a TextDocument object, represent just the 
text. They don't represent a logical view on the text, but instead the 
text buffer itself. Operations are independent of user state, so they 
do the same thing every time. TextPoints are tied to the text they 
point to, so as text is inserted, deleted, or changed.prior to a Text- 


Point, the TextPoint moves with it. EditPoints can almost be thought 
of as a byte offset into the text file. If something changes before the 
EditPoint, then the text at the EditPoint may have moved or 
changed. Another way to look at it is that the TextSelection object 
operates on a view of the text, whereas the EditPoint and TextPoint 
objects operate directly on the unfiltered text itself. 

That's enough about abstract objects for now. Let’s use a few to 


' create a new text editing function. 
I now have a working add-in, but it certainly seems like a lot of | 


' A More Complex Function: Justify 


Justify is an editing function that performs word wrapping on a 
paragraph. That means simply moving text from line to line to fill 
out, but not exceed, a particular line width. It’s the kind of function 
word processors do all the time, but text editors do not. I find it 
particularly useful when writing comments in my code, or when 
using my text editor to write e-mail. In fact, I won't move to a text 
editor unless it has, or I can write, a Justify function for it. 

Since paragraph is an ambiguous term for a text editor, I define 
it as a collection of lines of text up to, but not including, the first 
isi nele irene etal EE AEE CS 
add some functionality 
later that will allow a little 
more flexibility, but Pll 
start with this. 

The first decision I have 
to make is whether to op- 
erate on the view of the text 
(via a TextSelection) or on 
the raw text (via EditPoint 
and TextPoint). I’m going to choose the raw text, because it doesn't 
really make sense for paragraph justification to be affected by things 
like insert/overtype and the like. Its more important that it do 
exactly the same thing in all cases. Later I will use the text selection 
in effect when the function is invoked and add some user 
customizable properties. 

Hooking up a new function is by now fairly straightforward. I’ve 
added a call to the AddCommand function in OnConnection, 
added a check for the Justify function in both QueryStatus and 
Exec, added a call to the new JustifySimple function in Exec and, of 
course, added the JustifySimple function itself, shown in Figure 7. 

As its name implies, this version of the function is very simple. 
Using the current selection, it creates an edit point, then walks 


| forward in the text looking for a blank line. Once that's found, the 


code puts all the text in the range into a local variable. Note the use 
of the pointCur.Delete function to delete all the text in a range 
between two editpoints. Once the old text is deleted, the rest of the 
function becomes simple string manipulation as it breaks the text 
into lines of less than iWidth in length. The last editing function is 
a call to pointCur. Insert to insert all of the newly formatted lines of 
text into the document. 


Improvements to the Simple Justify Function 
Now Ill walk you through some incremental improvements to 
JustifySimple to make it more useful. 
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JustifySimple pays no attention to any selection that may have 
been in place when it was invoked. My first change is to check for a 
selection which spans lines, and if there is one, only justify the lines 
included in the selection. The major change is the use of TopPoint 
rather than ‘TextSelection.AnchorPoint as the beginning of the 
range. ActivePoint is where the caret is, and AnchorPoint is the 
opposite end of selection. TopPoint is always the upper-left point 
of the selection. Thus, if the TopPoint and Bottom Point are on the 
same line, the code operates as before, searching for the subse- 
quent blank line to define the range. If they are different, however, 
the code can use their line properties to define the range explicitly, 
and justify the text only on those lines. The code that locates the 
blank line in JustifySimple is replaced with this: 


txt = (TextSelection)applicationObject.ActiveDocument.Selection; 
pointCur = txt.TopPoint.CreateEditPoint(); 

lineStart = pointCur.Line; 

if (txt.BottomPoint.Line == pointCur. Line) 


{ 
<original blank line searching code> 


Figure 7 JustifySimple 
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else 


{ | 
lineEnd = txt.BottomPoint.Linet+l; 


Right now, JustifySimple is rather inflexible about its results; the 
width is fixed at iWidth, which has been hardcoded. Next, I'll let 
the start column and end column of a selection define the area in 
which the text will be justified. The rules for the amount of text 
processed wont change; if the selection is on a single line, then the 
code will still grab text until the next blank line or the end of the 
document. If the selection spans multiple lines, then it will justify 
only the text on those lines. 

The code in Figure 8 is placed immediately after the code that 
locates the blank line. You'll note that I’ve restricted this function- 
ality to happen only when a box selection is made in order to avoid 
unexpected results in Justify’s other modes of operation. Note also 
that the code checks the top and bottom VirtualDisplayColumn. 
Virtual Spaces, when enabled, allow you to place your cursor be- 
yond the end of a line. The spaces between the end of the line and 
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your cursor are virtual in that they don’t really exist in your file. If 
youre going to use the horizontal cursor placement to determine 
the right margin of your text for Justify, then enabling Virtual 
Spaces is almost a necessity. 

At some point prior to the reformatting loop, 1Width is calcu- 
lated as the difference between two columns 

iWidth = iColEnd - iColStart; 


and immediately prior to the pointCur.Insert call, the resulting 
line is padded from the left to put it in the correct left-hand column: 
szLineTemp = szLineTemp.PadLeft (iColStart - 1 + szLineTemp.Length,' '); 


Controlling Undo 

If you've been stepping through and trying out the code each 
step of the way, chances are you tried to use undo to restore your 
text. As you'll have seen, each editing operation represents a sepa- 
rate, undoable step. That’s not really how an editing function should 
operate—Justify should certainly be an atomic operation that you 
can undo ina single step. 

The UndoContext in the DTE is exactly the tool you need. By 
opening the context, all actions taken are bundled into a single 
undoable operation until the context is closed. 

I've added the following code to the beginning of the Justify 
function, as shown here: 


bool fUndoWasOpen; // undo context state on entry 


fUndoWasOpen = applicationObject.UndoContext. IsOpen; 
if (!fUndoWasOpen) 
applicationObject.UndoContext.Open("TextUtil Justify", false); 


It checks to see if an undo context is already open, in which case I 
won't open anew one. This allows Justify to become part of a larger 
undo construct, if one is created prior to calling it, without inter- 
fering. I then wrap the following lines in the finally section of a 
try...finally block; the UndoContext.Close at the end of the func- 
tion only happens if UndoWasOpen is false: 


if (!fUndoWasOpen) 
applicationObject.UndoContext.Close(); 


Finally, the function returns true. It is important to place all the 
code in Justify after the UndoContext.Open in a try block and the 
UndoContext.Close in the finally block. You want to be absolutely 
sure that the Open is matched with a Close, regardless of any 
exceptions thrown along the way. An UndoContext that is left open 
can eat up all subsequent editing operations, even after the add-in 
function has terminated. If that happens, the undo functionality 
in the IDE can stop working or can undo many more steps than 
the user would naturally expect. 


More Bells and Whistles 

The last functional change I'll make adds the ability to detect 
and preserve a string (such as the comment-starting “//”) that 
would be removed from the beginning of each line of prejustified 
text, and appended to the beginning of each line after the justifica- 
tion has occurred. To do this I'll give the Justify function a param- 
eter representing the string to look for. In this case, I'll pass in the 
double slashes, which I want to be preserved. 

The following code, inserted into Justify, turns off the string 


Figure 8 Specifying Margins 


prepending operation if the text does not begin with the string: 


if ("" l= szPrepend) 
if (!rgszLines[0].StartsWith (szPrepend) ) 
szPrepend = ""; 


In the code which collects the text into a single line, I need to check 
for and remove the prepending string on each line where it's en- 
countered, as shown here: 


if (0 < szPrepend. Length) 
if (szLineTemp.StartsWith (szPrepend) ) 
szLineTemp = szLineTemp.Substring (szPrepend.Length) ; 


And finally, I need to output the formatted line with the prepending 
string, as you can see in the following code: 

szLineTemp = szPrepend + szLineTemp.Trim() + "\r\n"; 

Now, to reformat an existing comment block, all I need to do is 
locate the position at the first line and execute the Justify function. 
To create a new comment block, make sure you add “//” to the 


beginning, and Justify fills in the rest. 


Lastly, I've added a second command, called JustifyMail, which 
is similar to Justify, except that I pass it the string I want prepended 
to lines in e-mail (“>”), and of course I'll give it a different key 
binding. In OnConnection I’ve added: 


AddCommand ("JustifyMail", "&Justify Mail", "Justify Text in Mail", 
"Globals “alte haiti, edit 4 


I’ve also added the appropriate checks in Exec and QueryStatus. At 
this point, the Justify routine itself is almost finished (see Figure 9). 
There are a few hardcoded values that the user should be allowed 
to define. Sounds like a job for an Options page. 


Adding a Page to the Options Dialog 

It turns out that adding a page to the Options dialog (available 
in Tools | Options) is easy once the details are clear. There are a few 
things you need to know. A tools options page is just an ActiveX" 
control. To use a C#-generated form as an Options page, youll 
need a shim control, which is nothing more than an ActiveX con- 
trol that hosts your form. (I'll provide one.) You know that an 
Options page and an add-in communicate only via the registry. 
The setup for an add-in needs to add a registry key to cause the 
Options page to load. It’s also helpful to know that the add-in and 
its Options page are really two separate pieces of code. 

That last item was by far the hardest for me to understand. Being 
used to monolithic projects where setting options was part of the 
application, I expected that creating options for my add-in would 
work similarly. I was quite wrong. Aside from sharing setup infor- 
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Figure 9 Justify 
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mation and registry keys, the two could well be 
completely separate projects. 

First, Pll finish off the code for Justify so that I 
can move on to the options page. The only change 
read the default for these new options from the 
registry. I've selected a total of three items that 
the user will be able to configure in the Options 
page: the default paragraph width (iWidth, in 
the code), the prepending string for justifying 
comments in code, and the prepending string 
for justifying e-mail. 

The registry should be reread prior to each 
function beginning its work in order to pick up 
any changes that the user might have made to 
options. To do this I’ve created a function, Load- 
_ Registry, and placed calls to it immediately above 
the calls to the Justify function in Exec. I’ve cre- 
ated object variables to hold the resulting values. 

After adding the using Microsoft.Win32 di- 
rective to make the proper functions available, 
LoadRegistry itself is very simple: 


private void LoadRegistry() 
{ 
RegistryKey key; 
key = Registry. LocalMachine. OpenSubKey 
("Software\\Microsoft\\VisualStudio\\7.0\\Addins\\TextUtil .Connect\\0ptions") ; 
iWidth = (int)key.GetValue("iwidth", 72); 
txtCodePrefix = (string)key.GetValue ("codeprefix", "// "); 
txtMailPrefix = (string)key.GetValue ("mailprefix", "| "); 


} 
Note that my original defaults remain, but only as parameters to 
the GetValue calls in case the registry keys don't exist. 

That's it. Justify is finished. Next up is the Options page itself. 

To create the form, I right-clicked on TextUtil in the Solution 
Explorer and selected Add and then Add User Control. I’ve called 
mine optionscontrol.cs. On that form, I placed three text controls 
named txtRightColumn, txtCodePrefix, and txtMailPrefix. I also 
added appropriate labels and set the tab order, but you can essen- 
tially make it look however you want. My version of the control is 
shown in Figure 10. 

To make a few more changes, I right-clicked on optionscontrol.cs 
in the Solution Explorer and selected View Code. First, added 


using Microsoft.Win32; 


to get the registry access support needed. The class also needs to 
inherit from IDT ToolsOptionsPage in order to provide the appro- 
priate support functions: 


public class OptionsControl : System.Windows.Forms.UserControl, 
IDTToolsOptionsPage 


The GetProperties, OnCancel, and OnHelp methods in options- 
control.cs are required, but can be empty. In OnAfterCreated (see 
Figure 11), the code loads the current values of options from the 
registry and places them into the text controls. This method is 
called each time the options page is selected. In OnOK (also in 
Figure 11), the code takes the current values that are in the text 
controls and puts them into the system registry. , 
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Figure 10 My User Control 


As I mentioned, the user control I’ve just created wont plug 
directly into the Tools.Options pages. For that you need a shim, 
which is an ActiveX control that the options control can be hosted 
in. | won't go into detail on the shim itself. A shim, VSToolsOptions- 
UserControl, is part of the downloadable code accompanying this 
article (see http://msdn.microsoft.com/msdnmag/code02.asp). All you need 
to do is add that shim as a subdirectory in the TextUtil project and 
add the separate C++ project to the solution. 

There is one change you'll need to make to the shim in order to 
use it. In VSToolsOptionsUserCtl.cpp, in the OnShowWindow 
method, it references a GUID. This is how the shim locates your 


Figure 11 OnAfterCreated and OnOK 
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Figure 13 TextUtil Options Dialog 


tools.options control. Change it to be the GUID used in the Guid- 
Attribute statement of optionscontrol.cs. Right-click the VSTools- 
Options UserControl project, build, and you have a shim. 

Finally, the appropriate modifications need to be made to setup 
to get the Tools.Option control installed. Select the TextUtilSetup 
project in the Solution Explorer, then click on the registry editor 
icon. There should already be several values under the key HKEY_ 
LOCAL_MACHINE\Software\Microsoft\VisualStudio\7.0\Add- 
ins\TextUtil.Connect. Under that key, add a subkey called Op- 
tions, and under that add a subkey called TextUtil. Under that 
subkey add one called Settings. In that key, create a single string 
value named Control with a value of “VSToolsOptionsUserCon- 
trolHost.VSToolsOp, which is the ProgID of the shim control. See 
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Figure 12 for the location of 
this key in the Visual Studio 
registry editor. The keys you 
created under Options cor- 
respond to the location in the 
Options page that your con- 
trol will appear, and the Con- 
trol setting is used by the IDE 
to locate the ActiveX control 
to place there. 

I've left optionscontrol.cs 
as part of my TextUtil project 
so it will be installed when 
the project its set up, but the 
shim control also needs to be 
laid down at setup time. To 
do so, right-click on the Text- 
UtilSetup project in the So- 
lution Explorer, select Add, then Project Output. In 
the dropdown, select VS ToolsOptions UserControl- 
Host, and in the list below it, select Primary Output. 

Now rebuild setup and install it. Press F5 and you 
should now have not only your add-in available in 
Visual Studio .NET, but also your Options page, as 
shown in Figure 13. If youre still breaking on every 
exception, don't panic when the IDE throws an ex- 
ception saying that some component of textutil.dll 
isnt found when you open up the Options page. 
That's actually part of the IDE’s mechanism for lo- 
cating the DLL containing the page. Let the IDE 
continue (or disable breaking on that particular ex- 
ception) and all should be well. 
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Conclusion 

I've only touched on text editing functionality here, but you can 
imagine the possibilities. Clearly, you can build up your own li- 
brary of editing functionality that meets your specific needs which 
can then be easily taken to any installation of Visual Studio .NET. 

Useful add-ins range from functions that allow you to examine 
and operate on code at the symbolic level, to manipulating the 
build environment, and even to plugging in entire applications. 
Many automation examples are available on the MSDN Web site, 
and I encourage you to check them out. 


Leo A. Notenboom is a long-time developer and former development manager at Microsoft, 
most recently with the Visual Studio .NET team. Leo can be reached at leon@exmsft.com. 
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long time ago, in a galaxy far away, I wrote one of my 
first articles for Microsoft Systems Journal (now 
MSDN’ Magazine). The article, “Peering Inside the 
PE: A Tour of the Win32 Portable Executable File 
Format, turned out to be more popular than I had 
expected. ‘To this day, I still hear from people (even 
within Microsoft) who use that article, which is still available from 
the MSDN Library (http://msdn.microsoft.com/library/en-us/dnwbgen/html/ 
msdn_peeringpe.asp). Unfortunately, the problem with articles is that 
they're static. The world of Win32* has changed quite a bit in the 
intervening years, and the article is severely dated. I'll remedy that 
situation in a two-part article starting this month. 

You might be wondering why you should care about the execut- 
able file format. The answer is the same now as it was then: an 
operating systems executable format and data structures reveal 
quite a bit about the underlying operating system. By understand- 
ing what's in your EXEs and DLLs, you'll find that you've become a 
better programmer all around. 

Sure, you could learn a lot of what I'll tell you by reading the 
Microsoft specification. However, like most specs, it sacrifices read- 
ability for completeness. My focus in this article will be to explain 
the most relevant parts of the story, while filling in the hows and 
whys that don't fit neatly into a formal specification. In addition, I 
have some goodies in this article that don’t seem to appear in any 
official Microsoft documentation. 


Bridging the Gap 

Let me give you just a few examples of what has changed since I 
wrote the article in 1994. Since 16-bit Windows’ is history, there's 
no need to compare and contrast the format to the Winl6 New 
Executable format. Another welcome departure from the scene is 
Win32s’. This was the abomination that ran Win32 binaries very 
shakily atop Windows 3.1. 
- Back then, Windows 95 (codenamed “Chicago” at the time) 
wasn't even released. Windows NT” was still at version 3.5, and the 


linker gurus at Microsoft hadnt yet started getting aggressive with | 


_ their optimizations. However, there were MIPS and DEC Alpha 
implementations of Windows NT that added to the story. 

And what about all the new things that have come along since 
that article? 64-bit Windows introduces its own variation of the 
Portable Executable (PE) format. Windows CE adds all sorts of 
new processor types. Optimizations such as delay loading of DLLs, 
section merging, and binding were still over the horizon. There are 
many new things to shoehorn into the story. 

And let’s not forget about Microsoft® .NET. Where does it fit in? 
To the operating system, .NET executables are just plain old Win32 
executable files. However, the .NET runtime recognizes data within 
these executable files as the metadata and intermediate language 
that are so central to .NET. In this article, Pll knock on the door of 
the .NET metadata format, but save a thorough survey of its full 
splendor for a subsequent article. 

And if all these additions and subtractions to the world of Win32 
weren't enough justification to remake the article with modern day 
special effects, there are also errors in the original piece that make 
me cringe. For example, my description of Thread Local Storage 
(TLS) support was way out in left field. Likewise, my description 
of the date/time stamp DWORD used throughout the file format 
~ isaccurate only if you live in the Pacific time zone! 

In addition, many things that were true then are incorrect now. I 
had stated that the .rdata section wasnt really used for anything 
important. Today, it certainly is. I also said that the .idata section 1s 
a read/write section, which has been found to be most untrue by 
people trying to do API interception today. 

Along with a complete update of the PE format story in this 
article, I’ve also overhauled the PEDUMP program, which dis- 
plays the contents of PE files. PEDUMP can be compiled and run 
on both the x86 and IA-64 platforms, and can dump both 32 and 
64-bit PE files. Most importantly, full source code for PEDUMP is 
available for download (see http://msdn.microsoft.com/msdnmag/ 
code02.asp), so you have a working example of the concepts and 
data structures described here. 


Overview of the PE File Format 

Microsoft introduced the PE File format, more commonly 
known as the PE format, as part of the original Win32 specifica- 
tions. However, PE files are derived from the earlier Common 


Object File Format (COFF) found on VAX/VMS. This makes sense | 
since much of the original Windows NT team came from Digital | 


Equipment Corporation. It was natural for these developers to use 
existing code to quickly bootstrap the new Windows NT platform. 


The term “Portable Executable” was chosen because the intent 
was to have a common file format for all flavors of Windows, on all 
supported CPUs. To a large extent, this goal has been achieved 
with the same format used on Windows NT and descendants, 
Windows 95 and descendants, and Windows CE. 

OBJ files emitted by Microsoft compilers use the COFF format. 
You can get an idea of how old the COFF format is by looking at 
some of its fields, which use octal encoding! COFF OBJ files have 
many data structures and enumerations in common with PE files, 
and P’ll mention some of 
them as I go along. 

The addition of 64-bit 
Windows required just a 
few modifications to the 
PE format. This new for- 
mat is called PE32+. No 
new fields were added, and 
only one field in the PE for- 
mat was deleted. The re- 
maining changes are 
simply the widening of 
certain fields from 32 bits 
to 64 bits. In most of these cases, you can write code that simply 
works with both 32 and 64-bit PE files. The Windows header files 
have the magic pixie dust to make the differences invisible to most 
C++-based code. 

The distinction between EXE and DLL files is entirely one of 
semantics. They both use the exact same PE format. The only 
difference is a single bit that indicates if the file should be treated as 
an EXE or as a DLL. Even the DLL file extension is artificial. You 
can have DLLs with entirely different extensions—for instance 
.OCX controls and Control Panel applets (.CPL files) are DLLs. 

Avery handy aspect of PE files is that the data structures on disk 
are the same data structures used in memory. Loading an execut- 
able into memory (for example, by calling LoadLibrary) is prima- 
rily a matter of mapping certain ranges of a PE file into the address 
space. Thus, a data structure like the IMAGE NT HEADERS 
(which I'll examine later) is identical on disk and in memory. The 
key point is that if you know how to find something in a PE file, 
you can almost certainly find the same information when the file is 
loaded in memory. 

It’s important to note that PE files are not just mapped into 
memory as a single memory-mapped file. Instead, the Windows 
loader looks at the PE file and decides what portions of the file to 
map in. This mapping is consistent in that higher offsets in the file 
correspond to higher memory addresses when mapped into 
memory. The offset of an item in the disk file may differ from its 
offset once loaded into memory. However, all the information 1s 
present to allow you to make the translation from disk offset to 
memory offset (see Figure 1). 

When PE files are loaded into memory via the Windows loader, 
the in-memory version is known as a module. The starting ad- 
dress where the file mapping begins is called an HMODULE. This 
is a point worth remembering: given an HMODULE, you know 
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what data structure to expect at that address, and you can use that 
knowledge to find all the other data structures in memory. This 
powerful capability can be exploited for other purposes such as 


> 


API interception. (To be completely accurate, an HMODULE isn't 


the same as the load address under Windows CE, but that’s a story | 


for yet another day.) 

A module in memory represents all the code, data, and resources 
from an executable file that is needed by a process. Other parts of a 
PE file may be read, but not mapped in (for instance, relocations). 
Some parts may not be mapped in at all, for example, when debug 
information is placed at the end of the file. A field in the PE header 
tells the system how much memory needs to be set aside for map- 
ping the executable into memory. Data that won't be mapped in is 
placed at the end of the file, past any parts that will be mapped in. 

The central location where the PE format (as well as COFF files) 
is described is WINNT.H. Within this header file, you'll find nearly 
every structure definition, enumeration, and #define needed to 
work with PE files or the equivalent structures in memory. Sure, 
there is documentation elsewhere. MSDN has the “Microsoft Por- 
table Executable and Common Object File Format Specification? 
for instance (see the October 2001 MSDN CD under Specifica- 
tions). But WINNT:H is the final word on what PE files look like. 

There are many tools for examining PE files. Among them are 
Dumpbin from Visual Studio, and Depends from the Platform 
SDK. I particularly like Depends because it has a very succinct way 
of examining a file's imports and exports. A great free PE viewer is 
PEBrowse Professional, from Smidgeonsoft (http://www.smidgeon- 
soft.com). The PEDUMP program included with this article is also 
very comprehensive, and does almost everything Dumpbin does. 

From an API standpoint, the primary mechanism provided by 
Microsoft for reading and modifying PE files is IMAGEHLP.DLL. 

Before I start looking at the specifics of PE files, it’s worthwhile 
to first review a few basic concepts that thread their way through 
the entire subject of PE files. In the following sections, I will discuss 
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PE file sections, relative virtual addresses (RVAs), the data direc- 
tory, and how functions are imported. 


PE File Sections 

A PE file section represents code or data of some sort. While 
code is just code, there are multiple types of data. Besides read/ 
write program data (such as global variables), other types of data 
in sections include API import and export tables, resources, and 
relocations. Each section has its own set of in-memory attributes, 
including whether the section contains code, whether it’s read- 
only or read/write, and whether the data in the section is shared 
between all processes using the executable. 

Generally speaking, all the code or data in a section is logically 
related in some way. At a minimum, there are usually at least two 
sections in a PE file: one for code, the other for data. Commonly, 
there's at least one other type of data section in a PE file. Pl look at 
the various kinds of sections in Part 2 of this article next month. 

Each section has a distinct name. This name is intended to con- 
vey the purpose of the section. For example, a section called .rdata 
indicates a read-only data section. Section names are used solely 
for the benefit of humans, and are insignificant to the operating 
system. A section named FOOBAR is just as valid as a section 
called .text. Microsoft typically prefixes their section names witha 
period, but it's not a requirement. For years, the Borland linker 
used section names like CODE and DATA. 

While compilers have a standard set of sections that they gener- 
ate, there's nothing magical about them. You can create and name 
your own sections, and the linker happily includes them in the 
executable. In Visual C++, you can tell the compiler to insert code 
or data into a section that you name with #pragma statements. For 
instance, the statement 

#pragma data_seg( "MY_DATA" ) 
causes all data emitted by Visual C++ to go into a section called 
MY_DATA, rather than the default .data section. Most programs 
are fine using the default sections emitted by the compiler, but 
occasionally you may have funky requirements which necessitate 
putting code or data into a separate section. 

Sections dont spring fully formed from the linker; rather, they 
start out in OBJ files, usually placed there by the compiler. The 


_ linker’s job is to combine all the required sections from OBJ files 


and libraries into the appropriate final section in the PE file. For 
example, each OBJ file in your project probably has at least a .text 
section, which contains code. The linker takes all the sections 
named .text from the various OBJ files and combines them into a 
single .text section in the PE file. Likewise, all the sections named 
.data from the various OBJs are combined into a single .data sec- 
tion in the PE file. Code and data from .LIB files are also typically 


| included in an executable, but that subject is outside the scope of 


this article. : 

There is a rather complete set of rules that linkers follow to 
decide which sections to combine and how. I gave an introduction 
to the linker algorithms in the July 1997 Under The Hood column 
in MSJ (see http://www.microsoft.com/msj/0797/hood0797.htm). A section 
in an OBJ file may be intended for the linker’s use, and not make it 


into the final executable. A section like this would be intended for 
the compiler to pass information to the linker. 

Sections have two alignment values, one within the disk file and 
the other in memory. The PE file header specifies both of these 
values, which can differ. Each section starts at an offset that's some 


multiple of the alignment value. For instance, in the PE file, a | 


typical alignment would be 0x200. Thus, every section begins ata _ 


file offset that’s a multiple of 0x200. 

Once mapped into memory, sections always start on at least a 
page boundary. That is, when a PE section is mapped into memory, 
the first byte of each section corresponds to a memory page. On 
x86 CPUs, pages are 4KB aligned, while on the IA-64, they re 8KB 
aligned. The following code shows a snippet of PEDUMP output 
for the .text and .data section of the Windows XP KERNEL32.DLL. 


Section Table 
01 .text VirtSize: 00074658 VirtAddr: 00001000 
raw data offs: 00000400 raw data size: 00074800 


02 .data VirtSize: 000028CA VirtAddr: 00076000 
raw data offs: 00074C00 raw data size: 00002400 


Once the imports table is initialized, the pages are then set back to 
their original protection attributes. 


Relative Virtual Addresses 


In an executable file, there are many places where an in-memory 
address needs to be specified. For instance, the address of a global 
variable is needed when referencing it. PE files can load just about 
anywhere in the process address space. While they do have a pre- 
ferred load address, you can’t rely on the executable file actually 
loading there. For this reason, it’s important to have some way of 
specifying addresses that are independent of where the executable 
file loads. 

To avoid having hardcoded memory addresses in PE files, RVAs 


are used. An RVA is simply an offset in memory, relative to where 


the PE file was loaded. For instance, consider an EXE file loaded at 
address 0x400000, with its code section at address 0x401000. The 


| RVA of the code section would be: 


The .text section is at offset 0x400 in the PE file and will be 0x1000 | 


bytes above the load address of KERNEL32 in memory. Likewise, 
the .data section is at file offset 0x74C00 and will be 0x76000 bytes 
above KERNEL32’s load address in memory. 

It’s possible to create PE files in which the sections start at the 
same offset in the file as they start from the load address in memory. 
This makes for larger executables, but can speed loading under 
Windows 9x or Windows Me. The default /OPT:WIN98 linker 


option (introduced in Visual Studio 6.0) causes PE files to be cre-_ | name of the DLL, The HMODULE that’s returned is just a load 


ated this way. In Visual Studio® .NET, the linker may or may not use 

/OPT:NOWIN98, depending on whether the file is small enough. 
An interesting linker feature is the ability to merge sections. If 

two sections have similar, compatible attributes, they can usually 

be combined into a single section at link time. This is done via the 

linker /merge switch. For instance, the following linker option com- 

bines the .rdata and .text sections into a single section called .text: 
/MERGE: .rdata=. text 


The advantage to merging sections is that it saves space, both on 
disk and in memory. At a minimum, each section occupies one 


(target address) 0x401000 - (load address)0x400000 = (RVA)0x1000. 

To convert an RVA to an actual address, simply reverse the pro- 
cess: add the RVA to the actual load address to find the actual 
memory address. Incidentally, the actual memory address is called 
a Virtual Address (VA) in PE parlance. Another way to think of a 
VA is that it’s an RVA with the preferred load address added in. 
Don't forget the earlier point I made that a load address is the same 
as the HMODULE. 

Want to go spelunking through some arbitrary DLLs data struc- 
tures in memory? Here’s how. Call GetModuleHandle with the 


address; you can apply your knowledge of the PE file structures to 
find anything you want within the module. 


The Data Directory 


There are many data structures within executable files that need 


_ to be quickly located. Some obvious examples are the imports, 


page in memory. If you can reduce the number of sections in an | 


executable from four to three, there’s a decent chance youl use one 
less page of memory. Of course, this depends on whether the un- 
used space at the end of the two merged sections adds up to a page. 

Things can get interesting when youre merging sections, as there 
are no hard and fast rules as to what’s allowed. For example, its OK 
to merge .rdata into .text, but you shouldn't merge .rsrc, .reloc, or 
.pdata into other sections. Prior to Visual Studio .NET, you could 
merge .idata into other sections. In Visual Studio .NET, this is not 
allowed, but the linker often merges parts of the .idata into other 
sections, such as .rdata, when doing a release build. 

Since portions of the imports data are written to by the Win- 
dows loader when they are loaded into memory, you might won- 


der how they can be put in a read-only section. This situation | 


works because at load time the system can temporarily set the 


attributes of the pages containing the imports data to read/write. — 


| defined meaning for what 
| it refers to. The IMAGE _ 


exports, resources, and base relocations. All of these well-known 
data structures are found in a consistent manner, and the location 
Lh ete hee ieee Sah Ee 
Directory. 

The DataDirectory is an 
array of 16 structures. 
Each array entry has a pre- 


DIRECTORY_ENTRY_ 
xxx #defines are array in- 
dexes into the DataDirect- 
ory (from 0 to 15). Figure 2 
describes what each of the 
IMAGE_DATA DIRECTORY_xxx values refers to. A more de- 


tailed description of many of the pointed-to data structures will 


i 
j 
i 
j 
i 
i 
j 
j 
j 
i 
i 


\ 
i 


be included in Part 2 of this article. 


Importing Functions 
When you use code or data from another DLL, youre importing 
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it. When any PE file loads, one of the jobs of the Windows loader is 
to locate all the imported functions and data and make those ad- 


dresses available to the file being loaded. I'll save the detailed dis- 


Figure 2 IMAGE_DATA_DIREC Values 
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_ cussion of data structures used to accomplish this for Part 2 of this 


article, but it's worth going over the concepts here at a high level. 
When you link directly against the code and data of another 
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DLL, youre implicitly linking against the DLL. You don’t have to 
do anything to make the addresses of the imported APIs available 
to your code. The loader takes care of it all. The alternative is 
explicit linking. This means explicitly making sure that the target 
DLL is loaded and then looking up the address of the APIs. This is 
almost always done via the LoadLibrary and GetProcAddress APIs. 

When you implicitly 
link against an API, Load- 
Library and GetProc- 
Address-like code still 
executes, but the loader 
does it for you automati- 
cally. The loader also en- 
sures that any additional 
DLLs needed by the PE file 
being loaded are also 
loaded. For instance, every 
normal program created 
with Visual C++" links 
against KERNEL32.DLL. KERNEL32.DLL in turn imports func- 
tions from NTDLL.DLL. Likewise, ifyou import from GDI32.DLL, 
it will have dependencies on the USER32, ADVAPI32, NTDLL, 
and KERNEL32 DLLs, which the loader makes sure are loaded 
and all imports resolved. (Visual Basic 6.0 and the Microsoft .NET 
executables directly link against a different DLL than KERNEL32, 
but the same principles apply. ) 

When implicitly linking, the resolution process for the main 
EXE file and all its dependent DLLs occurs when the program first 
starts. If there are any problems (for example, a referenced DLL 
that can't be found), the process is aborted. 

Visual C++ 6.0 added the delayload feature, which is a hybrid 
between implicit linking and explicit linking. When you delayload 
against a DLL, the linker emits something that looks very similar 
to the data for a regular imported DLL. However, the operating 
system ignores this data. Instead, the first time a call to one of the 
delayloaded APIs occurs, special stubs added by the linker cause 
the DLL to be loaded (if it's not already in memory), followed by a 
call to GetProcAddress to locate the called API. Additional magic 
makes it so that subsequent calls to the API are just as efficient as if 
the API had been imported normally. 

Within a PE file, there's an array of data structures, one per 
imported DLL. Each of these structures gives the name of the 
imported DLL and points to an array of function pointers. The 
array of function pointers is known as the import address table 
(IAT). Each imported API has its own reserved spot in the LAT 
where the address of the imported function is written by the Win- 
dows loader. This last point is particularly important: once a mod- 
ule is loaded, the IAT contains the address that is invoked when 
calling imported APIs. 

The beauty of the IAT is that there's just one place in a PE file 
where an imported API's address is stored. No matter how many 
source files you scatter calls to a given API through, all the calls go 
through the same function pointer in the IAT. 

Let's examine what the call to an imported API looks like. There 
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are two cases to consider: the efficient way and inefficient way. In 
the best case, a call to an imported API looks like this: 
CALL DWORD PTR [0x00405030] 


If youre not familiar with x86 assembly language, this is a call 
through a function pointer. Whatever DWORD-sized value is at 
0x405030 is where the CALL instruction will send control. In the 
previous example, address 0x405030 lies within the IAT. 

The less efficient call to an imported API looks like this: 

CALL 0x0040100C 


0x0040100C: 
UMP DWORD PTR [0x00405030] 


In this situation, the CALL transfers control to a small stub. The 
stub is a JMP to the address whose value is at 0x405030. Again, 
remember that 0x405030 is an entry within the IAT. In a nutshell, 
the less efficient imported API call uses five bytes of additional 
code, and takes longer to execute because of the extra JMP. 

Youre probably wondering why the less efficient method would 
ever be used. There's a good explanation. Left to its own devices, 
the compiler can't distinguish between imported API calls and 
ordinary functions within the same module. As such, the compiler 
emits a CALL instruction of the form 

CALL XXXXXXXX 


where XXXXXXXX is an actual code address that will be filled in 
by the linker later. Note that this last CALL instruction isn’t through 


_ a function pointer. Rather, it’s an actual code address. To keep the 


cosmic karma in balance, the linker needs to have a chunk of code 
to substitute for XXXXXXXX. The simplest way to do this is to 
make the call point to a JMP stub, like you just saw. 

Where does the JMP stub come from? Surprisingly, it comes 
from the import library for the imported function. If you were to 
examine an import library, and examine the code associated with 
the imported API name, youd see that it’s a JMP stub like the one 
just shown. What this means is that by default, in the absence of 
any intervention, imported API calls will use the less efficient form. 

Logically, the next question to ask is how to get the optimized 
form. The answer comes in the form of a hint you give to the 
compiler. The __declspec(dllimport) function modifier tells the 
compiler that the function resides in another DLL and that the 
compiler should generate this instruction 

CALL DWORD PTR [XXXXXXXX] 
rather than this one: 

CALL XXXXXXXX 


In addition, the compiler emits information telling the linker to 
resolve the function pointer portion of the instruction to a symbol 
named __imp_functionname. For instance, if you were calling 
MyFunction, the symbol name would be __imp_MyFunction. 
Looking in an import library, youll see that in addition to the 
regular symbol name, there’ also a symbol with the___imp___pre- 
fix on it. This ___imp___ symbol resolves directly to the IAT entry, 
rather than to the JMP stub. 

So what does this mean in your everyday life? If you're writing 
exported functions and providing a .H file for them, remember to 
use the ___declspec(dllimport) modifier with the function: 


Figure 3 IMAGE_FILE_ HEADER 


__declspec(dllimport) void Foo(void); 


If you look at the Windows system header files, you'll find that they 
use ___declspec(dllimport) for the Windows APIs. It's not easy to 
see this, but if you search for the DECLSPEC_IMPORT macro 
defined in WINNT:H, and which is used in files such as WinBase.H, 
youll see how __declspec(dllimport) is prepended to the system 
API declarations. 


PE File Structure 


Now let’s dig into the actual format of PE files. Pl start from the 
beginning of the file, and describe the data structures that are 
present in every PE file. Afterwards, I'll describe the more special- 
ized data structures (such as imports or resources) that reside 
within a PE’s sections. All of the data structures that I'll discuss 
below are defined in WINNT.H, unless otherwise noted. 

In many cases, there are matching 32 and 64-bit data struc- 
tures—for example, IMAGE_NT_HEADERS32 and IMAGE_ 
NT_HEADERS64. These structures are almost always identical, 
except for some widened fields in the 64-bit versions. If youre 
trying to write portable code, there are #defines in WINNT.H 
which select the appropriate 32 or 64-bit structures and alias them 
to a size-agnostic name (in the previous example, it would be 
IMAGE _NT_HEADERS). The structure selected depends on 
which mode youre compiling for (specifically, whether _WIN64 
is defined or not). You should only need to use the 32 or 64-bit 
specific versions of the structures if you're working with a PE file 
with size characteristics that are different from those of the plat- 
form youre compiling for. ‘ 


The MS-DOS Header 


Every PE file begins with a small MS-DOS" executable. The 
need for this stub executable arose in the early days of Windows, 
before a significant number of consumers were running it. When 
executed on a machine without Windows, the program could at 
least print out a message saying that Windows was required to run 
the executable. 

The first bytes of a PE 
file begin with the tradi- 
tional MS-DOS header, 
called an IMAGE_DOS_ 
HEADER. The only two 
values of any importance 
are e_magic and e_lfanew. 
The e_lfanew field con- 
tains the file offset of the 
PE header. The e_magic 
field (a WORD) needs to 
be set to the value 0x5.A4D. There’s a #define for this value, named 
IMAGE_DOS_SIGNATURE. In ASCII representation, 0x5A4D 
is MZ, the initials of Mark Zbikowski, one of the original architects 
of MS-DOS. 


The IMAGE_NT_ HEADERS Header 


The IMAGE _NT_HEADERS structure is the primary location 
where specifics of the PE file are stored. Its offset is given by the 
e_lfanew field in the IMAGE_DOS_HEADER at the beginning of 
the file. There are actually two versions of the IMAGE_NT_HEAD- 
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Figure 4 IMAGE _FILE Xxx 


ER structure, one for 32-bit executables and the other for 64-bit 
versions. The differences are so minor that I’ll consider them to be 
the same for the purposes of this discussion. The only correct, 
Microsoft-approved way of differentiating between the two for- 
mats is via the value of the Magic field in the IMAGE_OPTION- 
AL_HEADER (described shortly). 

An IMAGE_NT_HEADER is comprised of three fields: 


typedef struct _IMAGE_NT_HEADERS { 
DWORD Signature; 
IMAGE_FILE_HEADER FileHeader; 
IMAGE_OPTIONAL_HEADER32 OptionalHeader; 
} IMAGE_NT_HEADERS32, *PIMAGE_NT_HEADERS32; 


Ina valid PE file, the Signature field is set to the value 0x00004550, 
which in ASCII is“PE00”. A #define, IMAGE_NT_SIGNATURE, 
is defined for this value. The second field, a struct of type IM- 
AGE_FILE_HEADER, predates PE files. It contains some basic 
information about the file; most importantly, a field describing the 
size of the optional data that follows it. In PE files, this optional 
data is very much required, but is still called the IMAGE_OP- 
TIONAL_HEADER. 

Figure 3 shows the fields of the IMAGE_FILE_HEADER struc- 
ture, with additional notes for the fields. This structure can also be 
found at the very beginning of COFF OB] files. Figure 4 lists the 
common values of IMAGE_FILE_xxx. Figure 5 shows the mem- 
bers of the IMAGE_OPTIONAL_HEADER structure. 

The DataDirectory array at the end of the IMAGE_OP- 
TIONAL_HEADERs is the address book for important locations 
within the executable. Each DataDirectory entry looks like this: 


typedef struct _IMAGE DATA DIRECTORY { 


DWORD VirtualAddress; // RVA of the data 
DWORD Size; // Size of the data 
jie 
The Section Table 


Immediately following the IMAGE_NT_HEADERS is the sec- 
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tion table. The section table is an array of IMAGE_SEC- 
TION _HEADERs structures. An IMAGE SECTION HEADER 
provides information about its associated section, including loca- 
tion, length, and characteristics. Figure 6 contains a description of 
the IMAGE_SECTION_HEADER fields. The number of IMAGE _ 
SECTION_HEADER structures is given by the IMAGE_NT_ 
HEADERS. FileHeader.NumberOfSections field. 

The file alignment of sections in the executable file can have a 
significant impact on the resulting file size. In Visual Studio 6.0, 
the linker defaulted to a section alignment of 4KB, unless 
/OPT:NOWINS98 or the /ALIGN switch was used. The Visual Stu- 
dio .NET linker, while still defaulting to /OPT:WIN98, determines 
if the executable is below a certain size and if that is the case uses 
0x200-byte alignment. 

Another interesting alignment comes from the .NET file speci- 
fication. It says that .NET executables should have an in-memory 
alignment of 8KB, rather than the expected 4KB for x86 binaries. 
This is to ensure that .NET executables built with x86 entry point 
code can still run under [A-64. If the in-memory section align- 
ment were 4KB, the [A-64 loader wouldnt be able to load the file, 
since pages are 8KB on 64-bit Windows. 


Wrap-up 
That's it for the headers of PE files. In Part 2 of this article I'll 
continue the tour of portable executable files by looking at com- 
monly encountered sections. Then I'll describe the major data 
structures within those sections, including imports, exports, and 


resources. And finally, Pll go over the source for the updated and 
vastly improved PEDUMP. 


Matt Pietrek is an independent writer, consultant, and trainer. He was the lead architect for 
Compuware/NuMega’s Bounds Checker product line for eight years and has authored three 
books on Windows system programming. His Web site, at http://www.wheaty.net, has a FAQ 
page and information on previous columns and articles. 
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Figure 5 Continued from page 89 
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Figure 6 The IMAGE SECTION _HEADER 
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This article assumes you're familiar with Visual Basic .NET and ASP.NET 


ne of the many factors that contributed to the phe- 
nomenal success of ASP was the ease with which 
developers could create data-driven Web pages. A 
very common data-driven Web page, especially in 
an intranet setting, is one that generates reports. Such 
a page often pulls figures from a database and pre- 
sents the information to the visitor in an easy-to-digest manner. 
While displaying textual report information through an ASP page 
is simple enough, rendering such information in the form of graphi- 
cal charts is another challenge entirely. 

I first started creating ASP pages back in January 1998 when 
asked to develop an intranet reporting system for the consulting 
company I worked for. At the end of each day, each consultant 
would spend a few minutes on the company intranet entering the 
hours he or she had worked and for what project. The managers of 
each consulting group wanted to be able to look at reports that 
showed past revenue by individual consultant and group. While 
displaying the raw figures in text form was one way to present the 
information, the managers requested various charts and graphs 
illustrating past and expected revenues. 

To do this I chose a client-side solution, the Microsoft” MSChart 
ActiveX’ control, which was a hefty 750KB download and, at the 
time, wouldn't work on any browser software but the latest version 
of Microsoft Internet Explorer. Since I was developing in a con- 
trolled environment, these shortcomings weren't an issue, but they 
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ffipe sdnfbanneripa - Microsoft Internet Explorer 


#2] http: localhost/madnbanner 


Figure 1 Standard Ad Banner 


would have been if I had been working on an Internet solution. 

A more client-independent approach would have been to gen- 
erate the graphs and charts in the ASP page as a GIF or JPG image 
file, and then send the file to the client's browser. Such a task is 
impossible to do in ASP without using a COM component. Fortu- 
nately for ASP developers, there are a number of third-party COM 
components that can be used to create server-side graphs. I found 
links to 16 such components on ASPIn.com (http://www.aspin.com/ 
home/components/graphics/charts), which catalogs ASP resources, com- 
ponents, and information. 

With the advent of ASP.NET, however, you can create dynamic 
charts and graphs without a third-party COM component. The 
Microsoft .NET Framework contains an abundance of classes in 
the System.Drawing namespace that can, be used—in a stand- 
alone Windows’ -based application or on an ASP.NET Web page— 
to create and edit images 
in a variety of formats. 
Using these classes (I use 
C# in this article) you can 
quite easily create an 
ASP.NET Web page that, 
when requested, generates 
a chart based on database 
information. You can then 
send this image to the re- 
questing client's browser. 

Before tackling a com- 
plete dynamic chart, let's 
first take a look at how you can create some simple images using 
code for an ASP.NET Web page. 


Displaying a Simple Image using Code 

The System.Drawing namespace in the .NET Framework con- 
tains all of the classes you'll need to create and edit images. When 
creating images, youll use two classes: the Bitmap class and the 
Graphics class. Think of the Bitmap class as your canvas and the 
Graphics class as your paintbrush. Pll show you how to use the 
Bitmap class to create a palette to draw on, and, when I’ve com- 
pleted drawing, I'll use the Save method of this class to either save 
the drawing to the file system or send it directly to a stream. The 
Graphics class contains all of the methods that you'll need for 
drawing images, shapes, and strings. 

To create the canvas, I simply need to create a new instance of 
the Bitmap class, like so: 


Bitmap myBitmap = new Bitmap(width, height); 
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Now that I have a canvas, I need to create an instance of the Graph- 
ics class, create the paintbrush, and specify a canvas to use. I can 
accomplish this using the static Graphics method FromImage, 
which takes an Image instance as a single parameter and returns a 
resulting Graphics instance. (I can pass in the instance of the Bit- 
map class, since it is derived from the Image class.) 

Graphics myGraphics = Graphics. FromImage(myBitmap) ; 

At this point, I’m ready to start creating images, shapes, and 
strings on the canvas. Take a moment to fire up the .NET Frame- 
work documentation and examine the Graphics class. There youll 
find a vast array of methods for drawing any shape youll ever 
need. Notice that most of these methods come in two varieties: a 
DrawShape and a FillShape, such as DrawEllipse and FillEllipse, 
respectively. The Draw variant simply draws the outline of the 
shape, while the Fill variant draws the shape and fills the contents. 
For example, if you wanted to create a standard 468x60 pixel ad- 
vertising banner like the one in Figure 1, you could use the code in 
Figure 2 in your Page_Load event handler. 


Viewing the Image through an ASP.NET Web Page 


The code in Figure 2 is still missing one thing: a way to save the 
image. At the conclusion of the code, the MSDN’ Magazine adver- 
tising banner is stored in-memory, but it does no good there since 
I want to be able to view this image from a Web page. 

In outputting an image to a Web page, there are two approaches 
you can take: 

1. Save the image to the Web server's file system and use an 
HTML img tag to display the created image. 

2. Stream the binary contents of the image directly to the Output- 
Stream of the Response object. 


Figure 2 Page_Load Event Handler 


Both approaches have advantages and disadvantages. If you are 
creating an image that is fairly static (such as the advertising ban- 
ner example), you can employ the first option and persist the dy- 
namically created image to a file. For future requests to the 
image-generating ASP.NET Web page, the image can be served 
from the Web server's file system, rather than recreating the image 
each time the Web page is requested. This approach, however, 


Figure 3 Display image Saved to File System 
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Figure 4 Displaying Saved Images 


quickly loses its appeal if the images being created change over 
time, or if they can differ based on user input. Since each image 
generated needs a unique file name, as more and more images are 
generated, the file system would become inundated by these tem- 
porary images. For a more thorough discussion of this approach, 
check out the article “Charting with Office Web Components” by 
Bret Hern (see http://www.4guysfromrolla.com/webtech/022101-1.shtml). In 
the next two sections, I'll examine both options more closely. 

To save an image to the file system (the first option), use the Save 
method of the Bitmap class (which is inherited from the Image 
class). When using this method, you should pass in two param- 
eters: the physical path and file name of where to save the image to, 
and the format in which you want to save the image. To see the 
available image formats, view the ImageFormat members in the 
.NET Framework documentation. You'll note that the major image 
formats are available: GIF, ICON, JPEG, PNG, BMP, TIFE and so 
on. If you add the following line of code to the last line of the 
Page_Load event handler in Figure 2, the MSDN Magazine adver- 
tising banner would be saved to C:\Inetpub\wwwroot\ 
images\MSDNBanner.jpg: 


// Save the image as a Jpeg 
objBitmap.Save("C:\\Inetpub\\wwwroot\\images\\MSDNBanner. jpg”, 
ImageFormat.Jpeg) ; 


Since the backslash is the escape character in C#, you must use two 
successive backslashes in a string to insert a literal backslash. 

In order to display this banner from an ASP.NET Web page, all 
you need to do is add an img tag that references the image saved by 
the ASP. NET Web page: 


<img src="/images/MSDNBanner. jpg" /> 


Since the image will be generated and saved to the Web server's file 
system before the HTML content is sent to the browser, the image 
downloaded will be the one created by the ASP.NET page visited, 
assuming other users aren't visiting the same page simultaneously. 

Figure 3 illustrates the complete code for an ASP NET Web page 
that uses the first option for creating an image and displaying it in 
the browser. The output of the code is shown in Figure 4. 

The second option, streaming the image output directly to the 
Response object's OutputStream property, comes in handy if you 
are generating a high volume of images. Imagine if an image- 
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Figure 5 Display Image Streamed to Browser 


generating Web page generated different graphics based on, say, 
values input via a WebForm, and that you were employing the first 
option to display the dynamic image to the user. Rather than sav- 
ing the image to some constant, hardcoded file name, youd need 
to create unique file names for each image generated. This way, if a 
number of users were visiting the page concurrently and having 
different images constructed, each user would be guaranteed to 
receive his specific image. While creating unique file names is not 
difficult, you eventually end up with a number of old image files 
floating out on the Web server's file system. 

When using the second option, you do not need to concern 
yourself with saving the image to the file system; rather, you can 
send it directly to the user’s browser. Since this option sends the 
binary data of the image file to the browser, you cannot include 
other content in the ASP.NET Web page. That is, you cannot stream 
the image and send along textual HTML from the same ASP.NET 
Web page. Rather, with this technique, youll create an ASP.NET 
Web page that does nothing but display an image. Then, in order 
to display this image from a Web page, you reference this image- 
generating ASP.NET Web page using an img tag, like so: 


<img src="Generatelmage.aspx" /> 


In order to stream the image to the Response object’s Output- 
Stream, you need to use an alternate version of the Save method. 
To save an image's output to a stream, use the following version of 
the Save method: 


objBitmap.Save(stream, imageFormat) ; 


So, to stream the MSDN Magazine advertising banner to the 
OutputStream of the Response object as a JPEG, youd simply use: 
objBitmap.Save(Response.OutputStream, ImageFormat.Jpeg); 


The code in Figure 5 shows an ASP.NET Web page thats sole 
purpose is to send the binary content of a dynamically generated 
image to the client. This Web page cannot send both binary and 
textual content—rather, the Web page’s sole task is to send the 
binary content of the MSDN Magazine banner image, which is 
created on the fly each time the page is requested. 

Note that in the first line of code in Figure 5 (the Page_Load 
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event handler) I set the Response object's ContentType property 
to image/jpeg. Since I am sending the raw, binary content of the 
image, this setting tells the browser how to render this binary in- 
formation. If you forget to explicitly set the ContentType, you wont 
notice this when viewing the page through Internet Explorer; 
Netscape will display the binary information as text, so be sure to 
set the ContentType for maximum cross-browser compatability. 

There are two ways to view the image that's output using this 
option. You can visit the ASP.NET page directly through your 
browser or you can reference the ASP.NET page in an img tag. 

The code in Figure 6 shows a simple HTML page that displays 
the MSDN Magazine advertising banner; the output of this HTML 
page looks just like the output in Figure 4. 


Creating Pie Charts from Database Data 


Now that you know how to create a simple image from an 
ASP.NET Web page, you can create more complex (and useful) 
images. For the remainder of this article I'll look at how to use the 
.NET Framework drawing classes to create a pie chart from data- 
base information. I'll build all of this functionality into a set.of 
functions in an ASP.NET Web page that will end up streaming the 
dynamically created pie charts binary content to the Response 
object's OutputStream. 


While creating a set of page-level functions to display a pie chart 


Figure 6 HTML Page Displaying Advertising Banner 


7 Filling the DataSet 


will accomplish the task at hand, a more reusable solution would 
be to encapsulate this functionality into a custom-defined ASP. NET 
Web control or compiled custom control. One disadvantage of 
such an approach, though, would be that the custom-defined 
ASP.NET Web control or compiled custom control would have to 
save the image’ file to the Web server's file system and then render 
it from an appropriate img tag. While this isn’t difficult to accom- 
plish, youll have to deal with the disadvantages I mentioned ear- 
lier, including the fact that each time a chart is generated youll 
keep adding to the list of images on the Web server's file system. 
Of course, there are techniques you could employ to limit the 
number of image files stored, such as having the control traverse 
through the directory of saved pie chart images and delete all files 
older than, say, 15 minutes. While this approach isn't difficult to 
implement, it (and the creation of a custom-defined ASP.NET 
Web control or compiled control) is beyond the scope of this ar- 
ticle. However, I encourage you to research these topics. You can 
read more about retroactively deleting old files from Bret Hern’s 
article, “Charting with Office Web Components” (mentioned ear- 
lier). For more information on creating and using Web pagelets or 
creating custom, compiled controls, review the documentation at 
http://www.gotdotnet.com/quickstart/aspplus/doc/webpagelets.aspx and. http:// 
www.gotdotnet.com/quickstart/aspplus/doc/webctrlauthoring.aspx. 


The CreatePieChart Function 


To help make the pie chart generation process as generic as 
possible, I'll create a single function, CreatePieChart, with the fol- 
lowing definition: 


void CreatePieChart(String tablename, String dataColumnName, 
String labelColumnName, String title, int width) 


The first three input parameters specify the database information 
that I want to chart: tablename should be set to the name of the 
database table from which I will pull the data. The dataColumn- 
Name parameter specifies the name of the column from which I 


will pull the data for the pie chart. The labelColumnName param- 
eter indicates the name of the database column from which the 
label for each data point should be extracted. The fourth param- 
eter, title, specifies the chart's title. Width indicates how many pix- 
els wide you want the pie chart to be. 

To better understand how to use these three parameters, imag- 
ine that you had a database table named SalesFrom Associates that 
tracked sales per employee. In addition, say that this table con- 
tained columns named SalesAssociateName and TotalSales, where 
the SalesAssociateName listed the name of each sales associate, 
and TotalSales listed the total revenue generated by a particular 
sales associate. If you wanted to create a pie chart showing the 
distribution of sales for each associate, with a title of “Sales Break- 
down’ anda width of 400 pixels, you would call the CreatePieChart 
function like so: 


CreatePieChart("SalesFromAssociates", "SalesAssociateName”, 
"TotalSales”, "Sales Breakdown", 400); 


That's all there is to it. The CreatePieChart function would then 
query the database, construct the pie chart image, and stream it 
out to the Response object's OutputStream. 

I am not passing database connection information into the 
CreatePieChart function, but you may want to add this as an op- 
tional parameter to increase the flexibility of CreatePieChart. In 
the implementation that I'll be examining, a default database con- 
nection is assumed and used in the function. 

Notice also that I am not specifying the height for the pie chart, 
only the width. This is because the height of the chart will depend 
on other factors, such as the size of the title and legend. (The size of 
the legend depends on the number of rows in the database table 
you are graphing.) The actual pie chart maintains a one-to-one 
pixel ratio for the width and the height. That is, if you specify a 
width parameter of 400, the pie chart itself will be 400 pixels tall. 
The overall image generated by CreatePieChart, though, will be 
larger to account for the title and legend. 

There are a number of potential enhancements you could make 
to increase the flexibility and usefulness of the CreatePieChart 
function, but I'll discuss these after I've examined the code. The 
CreatePieChart function begins by connecting to the data source 
to retrieve the information for the pie chart. Since I need to be able 
to move through the database data a number of times, I need to 
use a DataSet. The code in Figure 7 shows how to connect to a 
database, fill a DataSet, and then disconnect from the database. 

At this point I have a filled DataSet and have closed the connec- 
tion to the database. Since the size of each wedge of a pie chart is 


equal to its value in proportion to the entire sum of the plotted 


data, I first need to calculate the total for the data I am plotting. 
This is accomplished in a simple for loop: 


// find the total of the numeric data 

float total = 0.0F, tmp; 

int iLoop; 

for (iLoop=0; iLoop < ds.Tables[0].Rows.Count; iLoop++) 

{ 
tmp = Convert. ToSingle(ds.Tables[0].Rows[iLoop][dataColumnName]) ; 
total += tmp; 

} 


Next, I create the Font objects for the title and legend fonts. Once 
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Ihave these Font objects created, I can determine how many pixels 
the legend and title will require: 


// we need to create fonts for our legend and title 
Font fontLegend = new Font("Verdana", 10), 
fontTitle = new Font("Verdana", 15, FontStyle.Bold); 


Now I need to calculate the amount of space needed for the title 
and legend. The space, in pixels, required by the title is equal to the 
number of pixels the fontTitle Font object requires. The Font ob- 
ject contains a Height property that provides this information. 
The height needed for the legend depends on how many data 
points I have, which is equal to the number of rows in the DataSet. 

Once I know both the legend and title heights, I can figure out 
the entire height for the image (the specified width plus the legend 
height plus the title height). Remember that the height of the pie 
chart is equal to the specified width, thereby maintaining a one-to- 
one pixel ratio. 


// We need to create a legend and title, how big do these need to be? 

// Also, we need to resize the height for the pie chart, respective to 

// the height of the legend and title 

const int bufferSpace = 15; 

int legendHeight = fontLegend.Height * (ds.Tables[0].Rows.Countt+1l) + 
bufferSpace; 

int titleHeight = fontTitle.Height + bufferSpace; 

int height = width + legendHeight + titleHeight + bufferSpace; 

int pieHeight = width; // maintain a one-to-one ratio 


Once I know the heights for the various pieces of the image, lam 
ready to start setting parameters for the image. First, though, I 
should create a Rectangle object, specifying the coordinates within 
which to draw the pie chart: 


// Create a rectange for drawing our pie 
Rectangle pieRect = new Rectangle(0, titleHeight, width, pieHeight); 


Additionally, I need to specify the colors to use for each wedge of 
the pie chart. One option would be to allow the user to pass in an 
ArrayList of predefined colors. The option I chose to use for this 
article was to create an ArrayList in the CreatePieChart function 
and populate it with random colors. This ArrayList, colors, con- 
tains as many items as there are rows in the DataSet: 


// Create our pie chart, start by creating an ArrayList of colors 
ArrayList colors = new ArrayList(); 
Random rnd = new Random(); 
for (iLoop = 0; iLoop < ds.Tables[0].Rows.Count; iLoopt++) 
colors.Add(new SolidBrush(Color.FromArgb(rnd.Next(255), 
rnd.Next(255), rnd.Next(255)))); 


Next I can (finally) begin creating the actual image. The Graph- 
ics class contains a FillPie method that draws a wedge of a pie 
chart. This method contains the definition: 


FillPie(Brush, Rectangle, Single, Single); 


I will be calling FillPie for each of the wedges I intend to draw in 
the pie chart. Before looking at the code that will perform the 
drawing of the pie chart, let’s examine what the input parameters 
for the FillPie method should be. The brush parameter indicates 
the brush to use to fill the pie wedge. I'll create a new solid brush 
instance for each separate wedge, based on the corresponding ele- 
ment in the colors ArrayList. 

The rectangle parameter specifies the bounds within which I 
am drawing the pie chart (youll remember that I already have 
defined the bounds via the Rectangle object pieRect). The first 
single parameter specifies the start degree of the pie wedge, while 
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the second single parameter indicates how many degrees the wedge 
should consume. 

Each pie wedge will consume some percentage of the 360 degree 
circle. To find this percentage, I need to divide the wedge’s value by 
the total value of all of the wedges (which I have in a local variable 
called total). This ratio, multiplied by 360, will yield the number of 
degrees a particular wedge should consume. Figure 8 shows the 
code used to draw the actual pie chart. 

To construct the pie chart, this code loops through each row in 
the DataSet and calls the FillPie method, starting from the 
currentDegree degree and sweeping over the needed number of 
degrees (the current wedge’s data point divided by the sum of the 
data points, times 360). Once I've drawn the current wedge, I in- 
crement currentDegree the appropriate number of degrees. 

At the conclusion of the for loop that is shown in Figure 8, the pie 
chart has been drawn. However, I still need to place the title and 
legend of the pie chart. Drawing the title is simple enough—as I 
discussed in the first example of this article, the Graphics class 
contains a DrawString method for displaying text: 


// Create the title, centered 

StringFormat stringFormat = new StringFormat(); 
stringFormat.Alignment = StringAlignment.Center; 
stringFormat.LineAlignment = StringAlignment.Center; 


Figure 8 Drawing the Pie Chart 


Figure 9 Displaying the Legend 


objGraphics.DrawString(title, fontTitle, blackBrush, 
new Rectangle(0, 0, width, titleHeight), stringFormat); 


Displaying the legend, however, requires a bit more work. I be- 
gin by drawing a border around the legend space using the 


DrawRectangle method. Next, a for loop steps through each row | 


in the DataSet. In each iteration of the loop, a small, filled rectangle 
is drawn with the data point’s wedge’s color. Next to this rectangle, 


the DrawString method is used to display the name of the data | 


point (taken from the developer-specified labelColumnName in- 
put parameter) along with its data point value. Finally, at the con- 
clusion of the for loop, a total of the data is displayed, as you can see 
in Figure 9. 

At this point in the process, all that remains for me to do is send 
the image’s binary content out to the 
browser. You may recall that to accomplish 
this I first set the Response object's 
ContentType property to the appropriate 
MIME type (“image/jpeg” in this case) and 
then used the Save method of the Bitmap 
class to write out the image to the Response 
object’s OutputStream property. 


// Since we are outputting a Jpeg, set the 
// ContentType appropriately 
Response.ContentType = "image/jpeg"; 


// Save the image to the OutputStream 
objBitmap.Save(Response. OutputStream, 
ImageFormat.Jpeg) ; 


That's it! An entire ASP. NET Web page 
that utilizes this function could consist of 
the code in Figure 10. This pie chart could 
be viewed directly from a browser or in- 
cluded in a Web page as an img tag. Figure 
11 shows the resulting ASP. NET Web page 
directly through a browser. 


| Fruity Pops - 4.07 


Possible Enhancements 

The CreatePieChart function lacks the 
bang and pizzazz that a third-party graph- 
ing component may provide, but this func- 
tion was created in less than 15 minutes, 
costs nothing (except my time), and, best 
of all, has the source code readily available 
for any future changes or enhancements 
you may be interested in making. 

One possible enhancement for the 
CreatePieChart function would be to add 
the ability to pass in a SQL string as opposed to a database table 
name. In its current state, the CreatePieChart graph can only cre- 
ate pie charts for databases that have very simple data models. 
Being able to specify a SQL string means you could create graphs 
where the data came from multiple tables, or graph only certain 
rows from a database table by specifying a WHERE clause. 

Another enhancement would be to either allow the developer to 
specify what colors to use for each pie wedge or have an XML file 


Purple Rain 1.1 


Total: 25.38 


& 


http: ilocalhost/msdn/CreatePiechart, aspx 


Price Breakdown 


© Chocolate City Milk - 2.01 
@ Bessie Brand 2% Milk - 1.19 
Funny Farms Milk - 1.29. 


® Super Sugar Strike i ey 


Extreme Orange - 0,89 

@ Kona Diet Cola - 1.1. 

@ Fizzy Fizzing Drink - 1.05 
© Marigold Whole Milk - 1.39. 


Figure 11 The Chart in ASP 


Figure 10 Using CreatePieChart 


of possible colors. In the current implemen- 
tation of CreatePieChart, the colors for each 
wedge are chosen randomly, which may 
lead to very similarly colored wedges in the 
chart. The Fruity Pops and Super Sugar 
Strike wedges in Figure 11, for example, are 
botha very similar shade of purple. By pro- 
viding a default set of colors or allowing 
you to choose the color arrangement, you 
could ensure that the pie charts contain 
unique colors. 


Conclusion 

Because ASP.NET allows you to use the 
classes from the .NET Framework, with a 
little bit of code you can create your own 
dynamic images from a Web page. These 
images can either be saved to the Web 
server's file system or streamed directly to 
the browser. All of the image-generation 
routines you will ever need are included in 
the .NET Framework. The charts and 
graphs you can create are limited only by 
your imagination. 

In this article I have looked at how to 
create a dynamic pie chart. In a book I co- 
authored, ASPNET: Tips, Tutorials, and 
Code (see http://www.samspublishing.com/detail_ 
sams.cfm?item=0672321432), I examine how 
to use similar techniques to create a dy- 
namic bar chart based on the data from 
two ArrayLists (which can easily be popu- 
lated with data from a database). Creating dynamic line graphs, 
scatter plots, and other common graphs are also possible. With 
ASP.NET it is now easy to present database information in the 
form of a graph. 


Scott Mitchell is the founder of 4GuysFromRolla.com and has been working with Microsoft Web 
technologies for the past four years. He has authored two ASP books and one ASP.NET book. 
Scott can be reached at Mitchell@4guysfromrolla.com. 
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THE ONLY TRULY COMPREHENSIVE INTERNET TOOLKIT 


NOW FOR MICROSOFT .NET! - NEW: IP*WORKS! .NET EDITION 
30+ COMPONENTS - 100% MANAGED CODE | 


".. 1P*Works! is a network object library that 
runs everywhere, does all of the things we'd 
like it to, is easy for all developers to learn, 
and is well supported by the vendor. For these 
reasons, we give IP*Works! our highest rating 
and recommend it for all Windows network 


development projects..." 
InfoWorld Review 


ae a 


A Comprehensive, No-Compromise, 
Professionally-Supported Solution 


With more than 30 components, 
IP*Works! provides more functionality 
than most competing products put togeth- 
er. It includes easy-to-use, standards- 
based, implementations of all major Inter- 
net Protocols, with an extensible architec- 
ture allowing custom changes and modifi- 
cations. Here is the current List: 


CertMegr, FTP, FileMailer, HTTP/S, 
ICMPPort, IMAP/S, [PDaemon/S, IPInfo, 
IPPort/S, LDAP/S, MIME, MX, Multicast, 
NNTP/S, NetClock, NetCode, NetDial, 
POPY/S, Ping, RCP, Rexec, Rshell, 
SMTP/S, SNMP, SNPP, SOAP/S, TFTP., 
Telnet/S, TraceRoute, UDPPort, Web- 
Form/S, WebUpload/S, Whois, XMLp. 


Since 1995, Used By Most Fortune 500s 


Initially introduced in 1995, IP*Works! is 
actively used by almost all Fortune 500 
and Global 2000 companies, as well as 
thousands of independent software devel- 
opers worldwide. It has won a number of 
awards and is highly regarded in the 
development community for ease of use, 
robust implementation, and outstanding 
support. 


Razor-Sharp Performance 


All components are fully optimized for 
the Internet, with minimal footprints and 
no dependencies in external libraries. 
Internal asynchronous socket architec- 
ture, results in very efficient, highly 
responsive applications. 


/n) software 


’ www.nsoftware.com 


RSA Certified SSL Security 


IP*Works! SSL adds SSL/TLS and Digi- 
tal:Certificate capabilities to the core 
IP*Works! package, providing Secure 
Web Browsing, Secure Client, Secure 
Server, Secure Mail, and Digital Certifi- 
cate Management Capabilities, all 
through easy-to-use plug-and-play interfa- 
Ces. 


Native Components for all Major 
Development Environments 


IP*Works! provides native components 
specifically targeted to your environment 
of choice for best performance and ease 
of use. The programming interfaces are 
uniform across editions, effectively 
eliminating the learning curves for cross- 
platform development. : 


Visual Basic Edition: Special version 
targeted to Visual Basic developers. 
ActiveX Edition: Compatible with all 
COM-compliant containers. 

ASP Edition: COM Library opti- 
mized for Active Server Pages. 
Scripting Edition: Easy interfaces tar- 
geted to VBScript developers. 

C++ Edition: C++ Classes packaged 
in a DLL - best for Visual C++. 
Delphi Edition: Native VCLs for Bor- 
land Delphi development. 

Kylix Edition: Native CLX Compo- 
nents for Borland Kylix (Linux) 

C++ Builder Edition: Native VCLs 
for Borland C++ Builder. 

Java Edition: Pure Java Beans, for 
cross-platform Java development. 


P.O. Box 13821, Research Triangle Park, NC 27709, USA 
Tel. 919.544.7770 - Fax 919.493.1225 - www.nsoftware.com 


Special Edition for Active Server Pages 


IP*Works! ASP Edition includes compo- 
nents especially designed for use in 
Active Server Pages. The programming 
interfaces have been completely rede- 
signed with the ASP programmer in mind, 
allowing for maximum expressiveness 
with a minimal amount of coding. As 
with other editions, special care has been 
taken to ensure a robust implementation 
with 100% availability, critical for server 
side applications. Furthermore, addition- 
al security features allow fine-grained 
administrative control, a must for shared 
hosting environments. 


Cross-Platform: Windows, Pocket PC, 
Linux, Solaris, Java, .Net, and beyond! 


In addition to Windows desktop and serv- 
er platforms, IP*Works! natively supports 
Windows CE, Linux, Java, as well as 
Microsoft .NET. The Java implementa- 
tion is Pure Java code, with no dependen- 
cies on external libraries, and runs on any 
standard JVM. The Kylix and C++ Edi- 
tions for Linux and Solaris are native 
ports. 


IP*Works! .NET Edition is written in 
100% managed code (compiled from a 
pure C# codebase). 


Fully Functional Free Trial On Website 


Does this look like yet another over-prom- 
ising ad written by some over-caffeinated 
marketing rep? Please don't take our 
word of for it! Get the free trial and see 
for yourself: http://www.nsoftware.com/ 


Copyright (c) 1995-2001 /n software inc. - All rights reserved. IP*Works! is a Trademark of /n software inc. All other Trademarks or Registered Trademarks are property of their respective owners. 


IP*Works! 


Stanley B. Lippman 
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hose of us in the C++ community feel somewhat 
like the older child in a family when the new baby is 
brought home for the first time. Everybody goes gaga 
over the newlittle tyke, and we're lucky if we even get 
a pat on the head. It’s hard not to feel ignored and a 
little bit hurt. Actually, it’s even worse in technology 
because the ground is constantly shifting, and keeping abreast is a 
matter of survival. 

Of course, today the Microsoft® .NET Framework is the new 
technology on the block—quite a feast at that, and everyone is 
oohing and aahing about the language called C#. If youre a C++ 
programmer, it is hard not to wonder if you ought to learn C#. 
After all, in the .NET discussion there is hardly a mention of C++, 
except to contrast it with C#. 

Are C++ programmers obsolete? Absolutely not! In this article 
Pll touch on what's new in the current release of Visual Studio’ 
.NET, and then give you some idea of the plans Microsoft has for 
the future of C++. Primarily, there are two aspects of C++ in 
Visual Studio .NET that I want to touch on: standard C++ and the 
Managed Extensions for C++. 

The motivation behind the recent progress in standard C++ 
was largely to maintain compliance; that is, to provide support for 
the International Organization for Standardization (ISO) language 
features. I’ll also talk about the Managed Extensions for C++ in 
terms of making C++ a .NET language. 


This article assumes you're familiar with C++ 
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Standard C++ in Visual Studio .NET 


Progress has been made in standards compliance within the 
following areas: 
- There is now covariant return type support in the definition 
of virtual functions. This is great news for those who write 
class hierarchies. 


- Static const integer 
members can now be 
initialized explicitly. 

- There is support for the 
implicit return of 0 
within main. 

Now I'll discuss each area 

briefly. 

Adding the covariant 
return type was the first 
modification of the C++ 
language approved by the 
standards committee. This is a fancy way of saying that the virtual 
function of a derived class can now return an instance of the de- 
rived class when the base class virtual function it is overriding 
returns an instance of the base class. It's an important design idiom 
in the support for class hierarchies, and it is a welcome addition to 
Visual Studio .NET. 

Here is an example of how it is typically used. Consider this 
abstract Query base class: 


class Query { 


public: 
virtual Query *clone() = 0; 
Hf ocean 

i: 


In the NotQuery derived class instance, clone returns a copy of a 
NotQuery object. For example: 


class NotQuery { 
public: 
virtual ??2? clone() 


{ return new NotQuery( this ); } 
ee 
public: 
Query *operand; 
3 


Without support for covariant return types, the return type of the 
NotQuery instance of clone must be Query”: 


// without covariant return type support 
virtual Query* clone() 
{ return new NotQuery( 
ENDS gy 


This works fine if you are assigning the return value of clone to a 
Query* pointer, like so: 


NotQuery::NotQuery( const NotQuery &rhs ) 
{ operand = rhs.operand->clone(); } 


But this fails when you want to explicitly assign its value to a 
NotQuery”, as in: 
NotQuery nq( new NameQuery( "Shakespeare" ); ‘ 


// oops: illegal assignment ... 
NotQuery *pnqO = nq->clone(); 


// ok: required explicit cast ... 
NotQuery *pnql = 
static_cast<NotQuery*>(ng->clone()); 
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With covariant return type support, you can explicitly declare 
the NotQuery clone instance to return a NotQuery*: 


// with covariant return type support 
virtual NotQuery* clone() 
{ return new NotQuery( this ); } 


This allows you to use clone in an intuitive fashion without requir- 
ing an explicit cast: 
// ok: implicit conversion .. 


Query *pq = ng->clone(); 


// ok: no conversion necessary .. 
NotQuery *png = nq->clone(); 


While explicit initialization of a static const integer member is 
not as critical a language feature as that of covariant return type, it 
provides an important design convenience in class situations re- 
quiring a constant expression, such as the definition of a fixed-size 
array. For example: 


class Buffer { 
static const int ms_buf_size = 1024; 
char m_buffer[ ms_buf_size ]; 

ia 


A static const integer member is the one instance in C++ in 
which a class member can be initialized explicitly within the class 
definition, thereby making the value available to other constructs 
within the class, such as the dimension size of m_buffer. Without 
this construct, the use of an enumerator as a symbolic constant 
was acommon workaround. 

The return value of main represents a programs exit status. By 
convention, an exit status of zero indicates program success. With 


Figure 1 Include File for Text Query Application 


Figure 2 Data Representation 
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exercises the STL container classes for parsing a text file and set- 
ting up an internal representation. Figure 1 shows the include file 
and Figure 2 shows the data representation. 

Query is the abstract base class of an object-oriented hierarchy 
for interpreting a query language. Figure 3 shows how a query ses- 
sion might run. The native invocation of the text query system 


looks like this: 


int main() 

{ 

TextQuery tq; 
tq. build_up_text(); 
tq.query_text(); 


Figure 3 Query Session 


} 


I want to expose the TextQuery interface to the .NET platform 
without having to touch the darn thing, let alone consider 
reimplementing it. After all, it works. I wasn’t sure if I wanted to 
move to the .NET platform if it meant I had to give up on my 
investment in native code. Fortunately, wrapping native code to 
expose it to the NET platform is an important benefit of managed 
C++. Figure 4 shows what the code for doing this looks like. 

The __gc modifier (shown in Figure 4) identifies the class as a 
managed class—a garbage collected class allocated on the com- 
mon language runtime’s managed heap. I declare the native class as 
a pointer member. I allocate it on the unmanaged heap through 
the new expression, the same as I do in native code. Because it is 
not garbage collected, I delete it within the destructor. Both build_ 
up_text and query_text serve as stub functions, dispatching the 
call to the actual TextQuery object. 

Figure 5 shows the revised main function, generated by the man- 
aged C++ project wizard. 3 

Now let’s discuss how to make use of the .NET Framework. If 
someone were to ask me what is the most significant weakness of 
ISO Standard C++, I would say it’s the fact that there is no stan- 
dard library for programming domains such as threading, net- 
work programming, regular expressions, XML, and so on. The 
Standards committee is planning to address this deficiency in its 


Figure 4 Wrapping Native C++ Classes 


standard C++, a main function without an explicit return value 
means the compiler inserts a 


return 0; 


prior to the end of main. With Visual Studio .NET, Visual C++" is 
finally compliant with this standard. 


Managed C++ in Visual Studio .NET 


The Managed Extensions for C++ in Visual Studio .NET allow 
for three primary application strategies: 

- They provide a .NET-managed wrapper class to an unman- 
aged API, thereby exposing existing C++ classes to the Micro- 
soft .NET platform. 

- They allow you to make use of the Microsoft .NET class 
framework, intermixing it with unmanaged C++. There are 
three aspects to the framework: core language support, such 
as collection classes and system I/O; foundation programming 
classes, such as support for threading, network sockets, and 
regular expressions; and application domain support, such 
as XML, ASP.NET and Web Services, Windows Forms, 
ADO.NET, and so on. 

- They let you write directly in the .NET environment just as 
you might with C# or Visual Basic’. With this release, however, 
there is no C++ support for RAD designers, such as those for 
Windows’ Forms and Web Forms. 

First, Pll discuss wrapping an unmanaged implementation. For 
the third edition of my book C++ Primer (Addison-Wesley, 1998), 
I created a relatively large text query applicatign which heavily 


Figure 5 Generated Main Fu 
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next cycle, but that’s years from now. What do you do in the mean- 
time? Fortunately, the .NET Framework provides an attractive so- 
lution. For example, Figure 6 shows a simple Socket server class 
utilizing the .NET Framework. It accepts phone number queries 
for employees of Northwind, the sample SQL database distributed 
with Visual Studio .NET. : 

Figure 7 is a sample output created by running the server and 
recording its handling of three clients. Figure 8 shows the imple- 
mentation of the Start function shown in Figure 6. The Start func- 
tion makes use of the Thread class to spawn independent threads 
to retrieve the data from the database and handle client connec- 
tions. Because WriteLine requires a reference parameter, you need 
to explicitly box the port value. 

The Exception class is the root of the .NET exception hierarchy. 
The ToString method displays a full stack trace, which is very cool. 
ThreadStart is a delegate type—a kind of generic pointer to both 
static and nonstatic member functions. 

I could go further into the implementation, but I think you can 
get a sense of the framework’s power and ease of use. More impor- 
tantly, you can see how easy it is to make use of it through C++. 


Hopefully after reading this brief look at C++ in Visual Studio 
.NET, you feel reassured that Visual C++ is not only still amember 
of the family, but an important family member at that! To under- 
score that importance, the Visual C++ team at Microsoft is work- 
ing hard on an interim release to deliver these features as soon as 
possible. In terms of ISO Standard C++, the team has made ex- 
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Figure 7 Server Output 


ceptional strides in compliance work. For the power programmer, 
this means templates, templates, templates. Third-party libraries 
that heavily utilize templates, such as Loki and Boost, now compile 
internally without workarounds. As they say in Hollywood, stick 
around. You ain't seen nothing yet! : 


Stanley B. Lippman is a new architect with the Visual C++ development team at Microsoft. He 
spent more than 12 years at Bell Laboratories where he worked on the original cfront C++ 
implementation. Stan is the author of C++ Primer, Inside the C++ Object Model, Essential C++, 
and the recent C# Primer, all published by Addison-Wesley. 
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Grady Booch Discusses .NET and the Ar 


Grady Booch; recognized internationally 


for his innovative work on software architecture, 
modeling, and the software engineering process. 
He has been with Rational Software Corporation 
as Chief Scientist since its founding in 1980. Grady 
is one of the original developers of the Unified Mod- 
eling Language (UML). He's the author of six best- 
selling books on computer science, including The 
Unified Modeling Language User Guide (Addison- 
Wesley, 1999) and the seminal Object-oriented 
Analysis and Design with Applications (Addison- 
Wesley, 1994). MSDN" Magazine recently caught 
up with Grady to discuss the impact of Microsoft’ NET Nand 
Visual Studio” .NET on the world of software development. 


Mspn MacazinE How would you describe the trends and the 
changes you've seen over the past five years in software develop- 
ment and how do you describe your influence on those trends? — 


GRADY Last summer I was invited to keynote the international — 


conference on software engineering on that very topic, the future 
of software. As Alan Kay once said, “The best way to predict the 
future is to invent it?’ So were certainly in the process of helping 
invent some of that future, but given that there are lots of other 
folks out there doing the same, I chose to interview about 500 
interesting people around the world. Those 500 included virtually 
every Association for Computing Machinery (ACM) and IEEE 
fellow working in the area of software engineering, every living 
Turing award winner, and lots of interesting CTOs and ClOs, and 
some CEOs as well. From that I began to draw some conclusions in 
terms of the future of the business as well as the future of software 
itself. Pll really concentrate upon the latter. 

There is no doubt that the presence of the Web has changed 
everything, not just in terms of how we deliver applications, but 
also the means by which we create those applications. We see a 
number of folks using the Web as their virtual meeting space for 
projects. I think that is a significant step forward. 

As I look at the general software engineering trends, I would say 
that there are a handful we can discuss. It really was in the late 
1990s that I think we, as an industry, began to understand what the 
best practices for software development are—what works, what 
doesn't work, and the kinds of tools that codify those practices. 
Certainly since that time there have been some interesting devel- 
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opments such as XP. And here I don't mean Win- 
dows XP, but the original definition of the term, 
extreme programming, which I think brought to 
the table some interesting ideas about the social 
dynamics and the psychology of small teams. Now 
the reality is that XP and the Rational Unified Pro- 
cess are not opposites of one another, but rather 
they complement one another very well. Indeed, if 
you look at the sizes of teams that organizations 
have, especially those that are building Web-cen- 
tric apps, they tend to be modest-sized teams. The 
[truth is, no team is an island and those teams tend 
to work in teams of other teams. Therefore, you really need the 
proper processes at all levels. 

From a technical perspective, I think there are several key un- 
derstandings that have happened over the last five years or so, in 
this order: the first is the mainstreaming of object-oriented tech- 
nology; the second is the creation of UML, which has given us a 
basis for acommon language and a blueprint for software, and last, 
the notion of software patterns as best typified by the work of the 
Gang of Four. What is interesting about patterns is that they repre- 
sent a step up in the next level of abstraction. Indeed, if you look 
across the whole history of software engineering, its one of trying 
to mitigate complexity by increasing levels of abstraction. And 
object-oriented technology followed by design patterns is indeed 
that natural trend. 

I think the advent of technology such as the Microsoft .NET 
Framework represents a realization by the industry that there is 
quite a bit that can be codified at the middle level. It really repre- 
sents the proper separation of concerns between those who are 
building applications and those who must architect the infrastruc- 
ture because what’s in .NET represents a lot of the infrastructure 
that, in previous decades, organizations had to build on their own. 
Furthermore, it builds off of so many wonderful standards like 
SOAP and XML, that it makes it far easier for organizations to 
build applications that are quite sexy and quite complex and that 
can do great things for their business. That's where we are today. 


Mispn MAGAZINE What are the changes you expect to see in the 
coming years? 

Graby That's really the role I have—to look beyond where we are 
today and into the future. As I think about the next three to five 
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years, I see two things on the horizon that are particularly interest- 
ing for me. The first one is the advent of what I call collaborative 
development environments (CDE), and I think this will be of im- 
mediate use to the readers of MSDN Magazine. Consider for a 
moment the creation of Windows’ 2000, which was developed by a 


team of people that was so large that they could not physically sit in _ 
the same room. I understand that oftentimes the team would use © 


Microsoft NetMeeting’ to keep in touch with the larger extended 
team. We see this happening in the construction and manufactur- 
ing industries. The use of the Web is the 
basis for development. 

I believe the same thing will emerge over 
the next few years for developing an envi- 
ronment for software. It really does repre- 
sent a discontinuity from the traditional, 
integrated development environment to the 
collaborative development environment— 
environments that are Web-centric and ar- 
tifact-centric, meaning the tools become 
more invisible and they can present mul- 
tiple views to different stakeholders. There 
are a variety of technologies that exist today 
in terms of things like NetMeeting and 
WebEx for conferencing and sharing of me- 
dia over the Web, discussion groups and virtual meeting spaces, 
and virtual project spaces on the Web. There is no one killer app- 
lication, but it’s really lots of small things that work together to 
form these CDEs. 

[alluded to this notion of multiple views, which leads me to the 
next great leap I see—the notion of aspect-oriented programming 
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(AOP), which has been pioneered by Gregor Kiczales of Xerox | 


PARC and others. In fact Charles Simonyi, in his work on inten- 


tional programming, really has a piece of the action as well. Charles, | 
Gregor, and I were together this last summer at DARPA and Na- — 


tional Science Foundation (NSF) meetings looking at the future of 
software and software research. The three of us realized that there 
really is something fundamental here in terms of how software 
development might be approached from a multidimensional per- 
spective. Charles had some really fascinating ideas about IP, as did 
Gregor. We bring to the table the notion of multiple views and 
building a system architecture. I think as I project out over the next 
several years, I see AOP becoming an interesting development. 
Keep in mind, it’s not that AOP is replacing OOP; rather, all the 
work we see going on with aspect-oriented programming, espe- 
cially at Gregor’s end, tends to complement what is already hap- 
pening with the UML and OO techniques. 

I guess the last thing I'd say is that software is still fundamentally 
the world’s most important industry. Even in these shrinking eco- 
nomic times, business, organizations, and individuals rely upon 
software. There will be no end to the need for the services that the 
professionals in our business provide. These are very exciting times. 


Mspn MacazINE Do you feel like you've had direct influence on all 
of those trends you've just discussed? 
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GRADY Yes, especially in the area of OO programming. I guess I 
could make the claim, or I will make the claim, that I probably 
published the first use of the notion of OO design back in 1982 or 
1984 by writing the first paper on the topic. Bjarne Stroustrup and 
I sort of found one another through our collective writings. It was 
in the late 1980s that he and I went off on a tour together because 
we found that his work in C++ and my work in object-oriented 
design really complemented one another. So I think there is some 
small piece I had in helping people use C++ effectively. 

Of course with the creation of UML, Dr. 
Ivar Jacobson, Dr. James Rumbaugh, and I 
were the key instigators. Even though we 
were the ones who were the original authors 
of the UML, the truth is that UML has gone 
far beyond us. We see the use of UML to 
model business processes for real-time em- 
bedded systems; and indeed there is cur- 
rent work to provide a UML mapping to 
Web Services as well. I think that is relevant 
because as organizations move to more and 
more complex things—technologies such 
as the Web Services Flow Language or XML 
itself—we find that as you become con- 
cerned with issues of scale, having a com- 
mon set of blueprints that all your stakeholders can deal with makes 
a significant difference in managing the complexity of the system. 
Then lastly, I keep my fingers in things like AOP and patterns and 
such, so I'ma busy guy. 


Mispn MAGAZINE What was your first reaction when you heard 
what Microsoft was doing with .NET? 

Grapy I thought it was great, because as I look at the ways people 
struggle with technologies on the Microsoft side and the COM/ 
COM+ world, and on the non-Microsoft side of CORBA, my 
reaction has always been that there is more complexity here than 
there needs to be. So I applauded the presence of .NET as the 
codification of many things people previously have had to do them- 
selves. I would claim also that .NET represents yet another step up 
in level of abstraction. Previously people had nothing to build 
upon. Then there were operating systems, and then there was 
middleware. Now there are things like .NET that raise the level of 
abstraction so that I, as a developer, can focus on those things that 
are fundamentally value-added for me—mainly the stuff about 
my business—and I have to worry less about all the infrastructure 
below me. Anything that reduces complexity and allows me to 
build applications of quality more quickly, I welcome, and .NET 
does that. 


Mspn MAGAZINE Do you think that the NET Framework will 
change practices of object-oriented analysis? 

GRADY Well, I want to answer that question in terms of methodol- 
ogy, but let me also answer it in terms of teams and processes. 
Increasingly over the last few years, I’ve seen organizations struggle 


' with using all of these technologies, and there has been consider- 
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able technology churn that made it very challenging to say what 
technology they should select. So we found within organizations a 
small set of people who really understood the middleware and all 
the plumbing very, very well. Then you had the people who under- 
stood the business very, very well. But getting those two teams to 
communicate was—and always has been—very challenging. You 
throw into the mix your database folks who sort of live and breathe 
schemas and know all that. Even worse, in terms of added com- 
plexity, you have all the people who are content creators. Those 
folks know HTML inside and out, and they can build wickedly 
beautiful Web pages. So all of a sudden for modern systems, you 
have a constellation of stakeholders that’s far more complex than it 
was in the past. So keeping those people together has always been 
challenging. The UML helps teams carry out the best practices of 
software development that we have identified. 

With the advent of Microsoft .NET, what you see is the opportu- 
nity for all those worlds to communicate much more 
effectively. NET raises the level of abstraction, so as 
someone who might know all the things about my 
business, it is easier for me to isolate or segregate the 
business parts of my project and build on these 
higher-level abstractions. 

From a methodology perspective, I think the pres- 
ence of NET and object-oriented technology are still 
incredibly complementary of one another. Because 
all well-structured systems we see that rely on this 
technology are still inherently object-oriented, NET 
presents—especially through Web Services—sets of 
objects that people must combine in interesting ways. 

I think .NET creates the opportunity for higher 
level frameworks as well. In fact, in that effort we have 
at Rational a thing called a Reusable Asset Specification (RAS), 
and Microsoft isa member of this consortium. This group is com- 
posed of all the major component vendors—IBM, Component 


Source, and FlashLine, among others. The initiative is to first specify _ 


a common way to deliver assets—code assets, test assets, release 
assets, vision assets, and requirements assets—all the things asso- 
ciated with the major framework. The RAS specification has been 
circulating for well over a year and is reasonably stable. And were 
tackling the .NET side first. So now the attention of these teams is 
on harvesting potential frameworks against .NET and other 
middleware so that we can deliver up higher-level patterns. You 
can think of this as representing yet another step up from the Gang 
of Four design patterns into the domain of frameworks. Once I 
deliver up frameworks (and, by the way, these are inherently OO- 
based), I then provide mechanisms that application builders can 
build against. So it’s bridging the gap between .NET and what has 
to be delivered. 


Mispn Macazine Visual Studio NET has incorporated quite a few 
more modeling features. What do you think about this? 

Graby I think it’s great. It recognizes from a Microsoft perspective 
that modeling is a good thing. I’ve certainly always known that, but 
then I’m a little bit biased. I think that whatever can be done to 
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push modeling further is an excellent thing. Here I’ve got to refer to 
the work of another gentleman, Edward R. Tufte, and his classic 
books Envisioning Information (Graphics Press, 1990) and The Vi- 
sual Display of Quantitative Information (Graphics Press, 2001). 
What he observes is that the right kind of models and the right 
kind of abstraction not only help you deal with complexity, but 
they also help you look at problems in a fundamentally different 
way so that you can break through that complexity. That's what 
UML is all about. That's why modeling is so relevant. Modeling 
helps you deal with complexity, and it helps different stakeholders 
communicate with one another. If I'm the business person, I know 
my business rules, but I really don’t want to know C# or Visual 
Basic. I really want to express these business rules in my language. 
That’s some of the basic tenets behind Charles Simonyi's work on 
IP by the way—the notion that you have a domain-specific repre- 
sentation of things. Moving down to the software level, that's where 
the UML sits, and that’s why I am delighted to see more and more 
modeling in Visual Studio .NET. 


Mspn MAGAZINE One of the things that is easier now 
with Visual Studio .NET is being able to mix mul- 
tiple languages in a project. What do you think about 
special opportunities or problems that this creates? 
Grapy | used to be a language bigot. I thought years 
ago that ADA was God's chosen language. Then | 
found C++, and I thought I was wrong, so I changed 
religions. Then I saw Smalltalk, then I saw other lan- 
guages, and I realized I need the right language for 
me technically. While the choice of language is often 
not a technical decision, there is a cultural decision 
associated with it—the culture of my team, what 
they've used before, the domain they have worked in, and so on. 
So, because I looked over the current crop of languages that are out 
there—C#, C++, Visual Basic’, and lots of other languages in that 
same space—I now believe that, yes, at some levels they are differ- 
ent, but at other levels they are also very similar. It's not so much the 
language that is essential for me unless I am talking exotic lan- 
suages like the Common Lisp Object System (CLOS) and the like. 
Were talking about most kinds of languages that developers work 
with. It’s not so much the language that is relevant to me; it’s all the 
stuff that surrounds that language—its frameworks, its tools, and 
its components. : 

The reality is, I can find very, very few projects that involve a 
single language. I was just talking to an architect of a company that 
builds cell phones. He was telling me about their next-generation 
phone, that it will include lots of different languages, from Assem- 
bly on up. That is the reality of most projects. They are not single 
languages, they are not homogeneous, they are heterogeneous. Like 
it or not, the culture demands that organizations deal with mul- 
tiple languages simultaneously. A single team might have a single 
language, but with the organization as a whole, you generally have 
multiple languages. Therefore, anything that will help bridge the 
gap and break down the walls between these languages is a great 
thing. That’s one of the things .NET does well. 
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Mspn [MAGAZINE Have you looked at C#? What do you think 
about its influence? 

GRADY Again, given that I am less bigoted about languages here 
days, I am less concerned about new languages that come out. | 
think C# has some wonderful features in it, and because it’s not the 


only language I can use with .NET, it’s a great thing. Relative to | 
C++, it’s a little simpler and a lot nicer in some ways. | still pre- | 


dominantly use C++ in the things I do, but then I work in a lot of 
systems besides just Web-intensive ones. 


Mspn MaGazine Another aspect of NET is being able to use side- 


by-side assemblies. Do you think this is good, or do you see this 
perhaps leading to sloppier releases because they can be easily fixed? 
Grapy As for sloppier releases, I don't think the marketplace will 
tolerate them to any greater degree than it has in the past, just 
because fixes can be implemented more easily. Anything that fa- 
cilitates an incremental process is a positive development. Here at 
Rational, we have ClearCase. ClearCase is a powerful tool because 
it supports multiple releases almost simultaneously and multiple 
views of system development. In today’s world, you never have a 
single kind of release, especially in distributed systems. You have 
different versions of things deployed in different places, and you 
are constantly making changes. So we need anything that facili- 
tates the rapid, quality, incremental release of systems 


Mspn Macazine Have you seen projects at 
Rational or at other companies where the 
architectural guidelines are set ahead of 
time, as you can do in Visual Studio with 
enterprise templates. Has that approach 
been successful? 

GRADY I am a great believer in architecture 
first. Here (in Visual Studio .NET) we have 
an IDE that lets the architect impose their 
view upon the world. In a sense, this allows 
some degree of multidimensional develop- 
ment and allows the architect to have some 
control, which isa good thing. Now, whether 
that kind of architecture control will be well 


received by organizations frankly depends upon how well they | 
te Yee P *"°Y | fundamentals that will prepare you to absorb technological change, 
understand the importance of architecture. From our experience, |_|. 
_ which you'll have to do over time. If youre moving from C++ to 
having a solid architecture is an excellent predictor of project suc- w ; 
| C#, itis not that great of aleap. Making the move from client/server 


cess. I don’t mean heavyweight kind of architectures, but architec- 
ture in the sense of codifying significant design decisions early. 


5 
5 
j 


One of the things I do at Rational is to serve as an architectural | 


mentor on projects, so I actually do a lot of architecting myself. 
About a year ago, I was working with a chief architect at a large 
Swiss bank that had just merged with another large Swiss bank. He 
looked at the systems that they had to build, and I'll paraphrase 
him in two ways. First he said that there aren't enough PhDs in all 
of Europe to build the thing he needed to build. And second, he 


said that the software fundamentally is the bank, so what they were | 
building was essential to the future of that organization. As the | 
architect, he realized they could have lots of people coding things | 


left and right, so there were some significant technological risks 
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ahead. The purpose of that architect team was to establish the 
basic frameworks and the basic mechanisms by which all applica- 
tions would be built. By developing those, validating those, mak- 
ing sure those worked before you start employing lots of other 
people, the architecture actually served as a means of attacking 
risks. To put it clearly, according to Tom Gilb, “Tf you dont actively 
attack the risks in your project, they will actively attack you.’ One 
of the major technical risks is the presence and absence of the 
strong architecture. By architecture, I don't mean “tight restric- 
tions; but rather the specification of the key mechanisms by which 
applications will be built. 


Mispn Macazine At the magazine, we hear points of view on both 
ends of the spectrum. We have many developers who are extremely 
excited about .NET and who have investigated it and have Web 
Services up and running even on beta software. Yet we also hear 
from those who are still trying to deal with a lot of legacy systems 
and really don’t want to hear about .NET yet. What advice do you 
have for developers today, and what do you see as the best things 
they could do to move toward the future? 
Graby Technology churn is always a challenge. You know, many 
legacy systems are what keep people in business right now, yet they 
still must move forward with new kinds of technology. What .NET 
prgvides owes he Services is really a very different way of 
7 ™ constructing systems. The shift toward sys- 
tems that are delivered up as services with 
the use of SOAP and XML to transport ob- 
jects across firewalls, in effect, is indeed the 
very natural direction Web-intensive sys- 
tems are going. In fact, if you look at all the 
stuff going on inside the W3C and Tim 
Berners-Lee’s notion of the Semantic Web, 
all these technologies push us more and 
more in that direction, so that kind of change 
is inevitable. I would therefore offer the gen- 
eral guidance to those teams to focus on 
some of the best development practices, ar- 
chitecture first, the use of modeling, con- 
trolling your change management; these are 


to Web-intensive systems has been jarring for some, but moving 
from Web-intensive systems as they're being created today to Web 
Services is not that great of a leap. I expect we will see organizations 
struggle to build their own kind of Web Services because they 
would initially choose to not build upon public services out there, 
unless they are provided by a platform member such as Microsoft. 
It simply has to do with trust, availability, security, and scalability. 
And so they will probably dabble by building their own services, 
and later build systems upon public services. 


Mspn MAGAZINE We hear a lot about design patterns, and you 
mentioned aspect-oriented programming. Do you include those 
in your general advice for teams? 


Grapy As for design patterns, absolutely. Design patterns are some- 
thing that all hyper-productive teams that I’ve encountered use. 
Whats great about design patterns is that they give a team a way to 
talk at higher levels of abstraction. When I'm at a project and say, 


“Oh you should use a proxy pattern here” or “You should use pat- ! 


tern X, they'll immediately know what I’m 
talking about. The best projects will start 
creating their own kinds of patterns, too, 
and that's great. So design patterns fit in as 
sort of platform-independent technology 
because they're a way of using object-ori- 
ented technology even more effectively. 

As for aspect-oriented programming, this 
is really something that’s a few years out. We 
see some ideas that are coming to fruition, 
but I certainly wouldn't want to bet my busi- 
ness on AOP at the moment. However, it 
certainly interests me as a technologist. | 
worry and care about these things because I 
need to help people make the next leap and 
to build quality systems. 


Mspn Macazine Are there comments youd like to add or are there 
additional messages you would like to convey to our readers? 
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Grapy If I were to summarize, I would say three things. First, 
software development is still the world’s most important industry, 
and so what we do as an industry is still fueling the world’s economy. 
Businesses of quality and enduring businesses still rely upon soft- 
ware. Organizations, countries, everyone relies upon software and 
that will not change. If anything, it will be- 
come more and more important over time. 

The second thing I observe is that soft- 
ware development is still wickedly hard. 
That's why we, as professionals in this field, 
must employ whatever we can to provide 
systems on time, with high quality, because 
in a sense the world is relying upon us. 

The third thing I'd mention is that it is an 
exciting time to be in the software industry 
because of all these things. I’m pleased to 
see new initiatives such as .NET, the steady 
adoption of best practices that we have at 
Rational, which complement what Mi- 
crosoft offers. And I’m pleased with things 


" like the RAS specification, design patterns, and such that I men- 


tioned. All these things contribute to the toolbox for the individual 
developer, the team of developers, and the teams of teams to help 
build those systems with quality. 
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COM+ and MTS, DCOM and MSMQ, Serialization in .NET 


KEN SPER Ge 


evelopers frequently ask me for clarification on Microsoft's 
strategy for the future with regard to COM+, Microsoft’ Trans- 
action Services (MTS) with its features of JIT activation and ob- 
ject pooling, Microsoft Message Queuing (MSMQ), and DCOM. 
What's in store for Web farms versus app servers versus ASP and 
component integration? Since everybody’s clamoring for answers, 
let’s take these questions one at a time. First, I'll deal with the 
COM-+ and MTS issue. 


Using COM+ and MTS 

COM.+ is alive and well, so if you need features of COM+ or 
MTS, you can use the appropriate technology with your Microsoft 
NET components. In my mind, components are part of any type 
of solution, distributed or not. A component in .NET looks like a 
COM component in that they are both DLLs containing classes 
that can be instantiated by another application. The main differ- 
ence between them is the way they are implemented, which is 
outside the scope of this discussion. 

When considering what components to use in an application, 


there are several options. Should you use COM+, MTS, or neither? 
Both COM+ and MTS are designed to work with COM compo- | 
nents. Thus, when you build a component to run in either, it must | 


work with the COM binary standard and must be registered in the 
registry before it will work. 

The .NET Framework (and thus Visual Basic .NET) supports 
COM+ and MTS through COM Interop services. A Windows- 
based application (either a COM component or other application 
that can calla COM component) can call a .NET component, and 
a .NET application can call a COM component. This two-way 


interoperability is quite powerful and allows you to mix technolo- — 


gies in your applications. 


As I said, COM+ and MTS were designed to work with COM | 


components. When you place a. NET component (assembly) in an 
MTS package or a COM+ application, the component can be 
called by a NET application in the same way as if it were not an 
MTS or COM+ component. 

One of the underlying considerations when using COM Interop 
is the overhead incurred. .NET and COM use different execution 
methods (.NET uses the Common Language Runtime; COM does 
not) and .NET assemblies and COM components are implemented 
differently (.NET uses a type standard while COM uses a binary 


standard). Calling from one environment to the other adds some | 


amount of overhead, so only do it when necessary. In fact, there are 
approximately 20 to 30 CPU instructions executed for each Interop 
operation. When you call a method on a class that is hosted in 
COM+, this overhead is incurred during each call. 

If you absolutely must have features that COM+ or MTS pro- 
vide, then host your com- 
ponent in COM-+ or MTS 
and make sure you need all 
that functionality. If your 
component is performing 
transactions on a single 
database and will always 
work against only one da- 
tabase, then you don't nec- 
essarily need COM+ to 
implement those transactions; you can implement them with 
ADO.NET. However, if you need object pooling or transaction 
support for multiple databases, then use COM+ or MTS. 

To implement a component in MTS or COM+, you should see 
the MSDN documentation for the NET Framework and check 
out the information on COM-+. The docs will show you how to 
implement the components and how to use various attributes to 
automate the process. 


Remote Communications Using DCOM and MSMQ 

Instead of DCOM, you can use either .NET Remoting or Web 
Services. What's the difference? Think about your applications and 
how you communicate between various application segments and 
consider an application architecture that has an ASP.NET front 
end. You can put the code in the application in several places. 

First, you can add the code into the ASP.NET code-behind page. 
This makes the page similar to most ASP pages, where the code is 
tied to one output page. In this scenario, the application is not 
really distributed at all; rather it’s a two-tier application with an 
ASP.NET front end and a database for the back end. 

Second, you could put the generic code in a module. A module 
file is a simple Visual Basic file in your project with a module 
definition. You can place both functions and global variables in the 
module, then you can use both of them from anywhere in the 
application. This lets the module take the place of include files for 
the purpose of storing common code. 

Third, you can begin to migrate the common code into a set of 
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classes. Classes are files or sections of a file that have a class defini- 
tion and contain an interface (properties and methods). A class 
can be created in your ASP.NET project, which makes it part of the 
project, or you can create a separate project and implement the 
class in it. This latter approach is preferred for common code be- 
cause you end up with a 
DLL just as you would in 
the COM world, and this 
DLL can be shared among 
many applications. 


access code that performs 
transactions. To illustrate, 
lll use the design in Figure 
1. This figure shows two 
.aspx pages calling a busi- 
ness object to get the information for the page. Either the Cus- 
tomer, Product, or Order object then calls the database layer object, 
which performs some type of action that either retrieves data from 
or sends data (or update information) to the database. 

This application does not necessarily need MSMQ, .NET 
Remoting, or Web Services because all of the components are on 
the same server. You could move the database layer component or 
the business components onto another server, but it’s almost al- 
ways going to be a faster way to put all of the components on the 


Let’s assume that the | 
class contains some data | 


same server as the ASP.NET application. Why? Because the com- | 


ponents can run inside the same application domain (process) as 
the ASP.NET application, eliminating interprocess communica- 
tion. This is the fastest way to access a component. Whenever an 
application calls out of process there is overhead involved, which 
can slow down your app. 

You can also split things up and put components on another 
server when there is a business need for it. For instance, suppose 
the application allows users to enter data that is processed and then 
sent to a database. Assume that the system gets heavy traffic and 


bottlenecks are frequent. One way to add some zip to the applica- | 


tion is to insert MSMQ into the process. Basi- 
cally, your application can collect the 
information from the user, let the user know it is 
processing the information, then send the in- 
formation over MSMQ. The application on the 
other end of the queue can pull the information 
off the queue and update the database. The per- 
formance in this type of application willbe quite 
good because the user does not have to wait for | 
the database update. This structure will only 
work, however, if the application can support 
an architecture where you can have this type of 
disconnected operation. 

Of course, there are also many other times 
when you need a queuing system and MSMQ 
can be used in those scenarios as well. The 
System.Messaging namespace includes classes 
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Figure 1 Order Architecture 


that allow you to add queuing support to your applications. The 
queuing features are also integrated in Visual Studio .NET to allow 
you to easily access these features from your application. 

In moving the database layer to the database server you could 
expose the database component with either a Web service or via 
.NET Remoting. Using either of these technologies, you could also 
create a component server for each component. You can use .NET 
Remoting or Web Services in this scenario, depending on your 
needs. In one scenario, the Application Server hosts the ASP NET 
application and the Component Server hosts the components used 
by the Application Server. There are two ways the application on 
the Application Server can communicate with the components on 
the other server. 

First, you could simply create a Web service on the Application 
Server and have it provide methods to access the methods of the 
various components. This approach allows an application or com- 
ponent on the Application Server to access the components on the 
Component Server through the Web service. The advantage of this 
approach is that it’s flexible and quite easy to do. The downside is 
that it requires you to create a Web service explicitly to expose 
methods of the classes. 

Second, the applications on the Application Server could access 
the components on the other server using .NET Remoting, which 
is quite flexible and has advantages over Web Services in many 
scenarios. .NET Remoting is simple to set up. The .NET Remoting 
architecture is built into the .NET Framework and provides the 
architecture you need for interprocess communication between 
components on different systems. The architecture works by pro- 
viding a transport channel that your applications can use to com- 
municate over the network. 

The .NET Remoting support extends to many different areas 
such as built-in security. You also control the security of the data 
transmitted between the two components. One difference from 
Web Services is its ability to change the type of packet transmitted 
between the end points of a call. Web Services is based on the 
industry standard Simple Object Access Protocol (SOAP). 
Remoting can use SOAP, but can also use XML and even binary 
formatting. You choose the format type. You may 
prefer binary because it is more secure and more 
compact than a verbose XML format. 

The architecture shown in Figure 2 is slightly 
more complex. There is now a minicomputer on 
the LAN and a Web server that is connected to 
the LAN across a firewall. The applications on 
these different servers and the clients that use 
those applications communicate by using either 
Web Services or .NET Remoting on all of the 
servers and the clients can connect with either. 
Because most Web servers can host Web Ser- 
vices, the .NET applications can also all talk to 
the minicomputer through those services, and 
vice versa. Then, minicomputer applications can 
call Web Services exposed on the .NET servers. 
.NET Remoting can also communicate with 
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servers not running .NET, enabling .NET applications to commu- 
nicate with servers and apps on different operating systems. 

Of course, firewalls can be a problem. Since they frequently 
support HTTP, but no other protocols, what happens between the 
Web server and the other servers? Of course, Web Services will 
work in this scenario, since HTTP is the protocol. .NET Remoting 
also supports HTTP as the transmission protocol, but you can 
also use TCP/IP for performance or security reasons. 


Serialization in .NET 

For the many readers who have asked about serialization in 
.NET, I'll provide a brief overview here. In general, a class provides 
a serialize method that pulls data out and a deserialize method that 
takes a stream and places it back into the class. 

In the past, it was a programmers job to handle this serializa- 
tion. Now, this functionality is built into the .NET Framework. 
Think about a salesman who needs to download a set of data from 
a server to a laptop before going to see a client. Then he works with 
the data locally and later reconnects to the server application to 
dump the data back to it. The workstation application can connect 
to the server via a Web service, which can call a method in a class 
that retrieves the data. The data is serialized and the results are sent 
to the client. The client can then store those results locally by sav- 
ing the serialized XML stream. Later, the salesman can restart the 
application to load the XML stream into a local copy of the class. 
Later, the application can send the serial stream back to the server 
application where it is deserialized and the database is updated. 

Other classes in .NET use serialization also. For instance, the 
DataSet will automatically serialize and deserialize itself in and out 
of an XML stream. .NET Remoting and the queuing support use 
serialization as well. 


Send your questions and comments for Ken to basics@microsoft.com. 


Ken Spencer works for the 32X Tech Corporation (http://www.32X.com), which produces a line 
of developer courseware. Ken also spends much of his time consulting or teaching private 
courses. 
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Array Types in .NET 
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| rrays are mechanisms that allow you to treat several items as a 
P“A single collection. The Microsoft’ .NET Common Language 
Runtime (CLR) supports single-dimensional arrays, multidimen- 
sional arrays, and jagged arrays (arrays of arrays). All array types 
are implicitly derived from System.Array, which itself is derived 
from System.Object. This means that all arrays are always reference 
types which are allocated on the managed heap, and your app’s 
variable contains a reference to the array and not the array itself. 
The following code makes this point clearer: 


// Declares a reference to an array 
// Create array of 100 Int32s 


Int32[] myIntegers; 
myIntegers = new Int32[100]; 


On the first line, myIntegers is a variable that is capable of pointing 
to a single-dimensioned array of Int32s. Initially, myIntegers will 
be set to null since I have not allocated an array. The second line 
shown above allocates an array of 100 Int32 values; all of the Int32s 
are initialized to 0. Even though Int32s are value types, the memory 
block large enough to hold these values is allocated from the man- 
aged heap. The memory block contains 100 unboxed Int32 values. 
The address of this memory block is returned and saved in the 
variable myIntegers. 
You can also create arrays of reference types: 


Control[] myControls; // Declares a reference to an array 
myControls = new Control[50]; // Create array of 50 Control references 


On the first line, myControls is a variable that is capable of point- 
ing to a single-dimensioned array of Control references. Initially, 
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Figure 1 Arrays in the Managed Heap P 
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myControls will be set to null since I have not declared an array. 
The second line allocates an array of 50 Control references; all of 
these references are initialized to null. Since Control is a reference 
type, creating the array only creates references; the actual objects 
are not created at this time. The address of this memory block is 
returned and saved in the 
variable myControls. 
Figure 1 shows how ar- 
rays of value types and ar- 
rays of reference types look 
in the managed heap. The 
Controls array show the 
result after the following 


lines have executed: 
myControls[1] = new 
Button(); 


myControls[2] = new TextBox(); 
myControls[3] = myControls[2]; 
myControls[46] = new DataGrid(); 
myControls[48] = new ComboBox(); 
myControls[49] = new Button(); 


Common Language Specification (CLS) compliance requires 
that all arrays be zero-based. This allows a method written in C# to 
create an array and pass the array’s reference to code written in 
another language such as Visual Basic’. In addition, since zero- 
based arrays are by far the most common, Microsoft has spent alot 
of time optimizing their performance. However, the CLR does 
, support non-zero-based arrays but they are discouraged. For 
those of you who do not care about performance and cross- 
| language portability, I will demonstrate how to create and use 


// 2 elements refer to the same object 


non-zero-based arrays later in this section. 

Youll notice that Figure 1 shows that each array has some 
additional overhead information associated with it. This in- 
formation contains the rank of the array (number of dimen- 
_ sions), the lower bounds for each dimension of the array 
(almost always 0), and the length of each dimension. The 
overhead also contains the type of each element in the array. 
Shortly, Pll mention the methods that allow you to query this 
overhead information. 

So far, ’'ve shown examples demonstrating how to create 
single-dimension arrays. When possible, you should try to 
stick with single-dimensioned, zero-based arrays (sometimes 
_ referred to as SZ arrays or vectors). This is because SZ arrays 

give the best performance since there are specific intermedi- 
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ate language (IL) instructions (such as newarr, ldelem, ldelema, | 


Idlen, and stelem) for manipulating them. However, if you prefer to 


examples to choose from: 


// Create a 2-dimensional array of Doubles 
Double[,] myDoubles = new Double[10, 20]; 


// Create a 3-dimensional array of Strings 
StringL,,] myStrings = new String[5, 3, 10]; 


As mentioned earlier, the CLR also supports jagged arrays and 


m.Array Methods 

Member Type ae | 
_Readonly instance property 
Instance method — _ 
Readonly instance property 
‘Instancemethod 
: Instance method _ 
Readonly instance property : 
: Readonly instance property 
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single-dimensional arrays; zero-based jagged arrays have the same 


_ performance as normal SZ arrays. However, accessing elements of 
work with multidimensional arrays, you may do so. Here are some | 


a jagged array means that two or more array accesses must occur. 


| Note that jagged arrays are not CLS-compliant (because the CLS 
_ doesn't allow a System.Array object to be an element of an array) 
_ and cannot be passed between code written in different program- 
_ ming languages. Fortunately, C# does support jagged arrays. Here 
"are some examples of how to create an array of polygons, where 


each polygon consists of an array of Point instances: 


// Create a 1-dimensional array of Point-arrays 
Point[][] myPolygons = new PointL3][]; 


// myPolygons[0] refers to an array of 10 Point instances 
myPolygons[0] = new Pointl10]; 


// myPolygons[1] refers to an array of 20 Point instances 
myPolygons[1] = new Point[20]; 


// myPolygons[2] refers to an array of 30 Point instances 

myPolygons[2] = new Point[30]; 

// Display the Points in the second polygon 

for (Int32 x = 0, 1 = myPolygons[1].Length; x < 1; xt) 
Console.WriteLine(yPolygons[1][x]); 


Note that the CLR always verifies that an index into an array is 
valid. In other words, you cannot create an array with 100 elements 
in it (numbered 0 through 99) and then try to access the element at 
index 100 or -5. Attempting to do so will cause a System.IndexOut- 
OfRangeException to be thrown. Allowing access to memory out- 
side the range of an array would be a breach of type safety and a 
potential security hole and the CLR doesn't allow verifiable code 
to do this sort of access. 

Usually, the performance associated with index checking is not 
substantial because the just-in-time (JIT) compiler normally 
checks array bounds once before a loop executes instead of once 
for each loop iteration. However, if youre still concerned about a 
performance hit of the CLR’s index checks, then you can use un- 
safe code in C# to access the array. 


All Arrays are Implicitly Derived from System.Array 

The System.Array type offers several static and instance mem- 
bers. Since all arrays are implicitly derived from System.Array, these 
members can be used to manipulate arrays of value types or refer- 
ence types. Youll also note that Array implements several inter- 
faces: ICloneable, [Enumerable, ICollection, and IList. These 
interfaces allow arrays to be conveniently used in many different 
scenarios. Figure 2 summarizes the methods offered by System.Array 
and the interfaces that it implements. 


Casting Arrays 

For arrays with reference type elements, the CLR allows you to 
implicitly cast the source array’s element type to a target type. For 
the cast to succeed, both array types must have the same number 
of dimensions and there must be an implicit or explicit conversion 
from the source element type to the target element type. The CLR 
does not allow the casting of arrays with value type elements to any 
other type. However, using the Array.Copy method, you can create 
a new array that has the desired effect (see Figure 3). The Array. Copy 
method is incredibly useful and is used frequently by the NET 
Framework Class Library. Figure 4 shows another example of the 
usefulness of Copy. 


Passing and Returning Arrays 


Arrays are always passed by reference to a method. Since the 
CLR doesnt support the notion of constant parameters, this means 
that the method is able to change the elements in the array. If you 
don’t want to allow the method to modify the elements, then you 
must make a copy of the array and pass the copy into the method. 


Note that the Array.Copy method does a shallow copy, and there- 
fore if the array’s elements are reference types, the new array refers 
to the already existing objects. 

To obtain a deep copy, you may want to clone the individual 
elements, but this requires that each object’s type implements the 
ICloneable interface. Alternatively, you could serialize each object 
to a System.IO.MemoryStream and then immediately deserialize 
the memory stream to construct a new object. Depending on the 
object’s types, the performance of these operations can be prohibi- 
tive and not all types are serializable either. 

Similarly, some methods return a reference to an array. If the 
method constructs and initializes the array, then returning a refer- 
ence to the array is fine. But if the method wants to return a refer- 
ence to an internal array maintained by a field, then you must 
decide if you want the method's caller to have direct access to this 


Figure 3 Using Array.Copy 


Figure 4 More Uses for Copy 
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Figure 5 Iterating through an Array 


array. If you do want it to have access, then just return the array’s 


reference. Most often you do not, and the method should con- 
struct a new array and call Array.Copy, returning a reference to the 
new array. Again, you may want to clone each of the objects before 
returning the array reference. 

If you define a method that is to return a reference to an array 


and that array has no elements in it, then your method can either 


return null or a reference to an array with zero elements in it. When 
you are implementing this kind of method, you are strongly en- 
couraged to implement the method returning a zero-length array 
because it simplifies the code that a developer calling the method 
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Figure 6 Access without Index Checking 


must write. For example, this easy-to-understand code runs cor- 
rectly even if there are no appointments to iterate over: 


// This code is easier to write and understand 

Appointment[] appointments = GetAppointmentsForToday(); 

for (Int32 a = 0, 1 = appointments.Length; a < 1; a++) { 

In comparison to the previous code, the following code runs 
correctly if there are no appointments to iterate over, but it’s slightly 
more difficult to write and understand: 


he Great Wall of China 
just a backya rd fence. 


// This code is harder to write an understand 
Appointment[] appointments = GetAppointmentsForToday(); 
if (appointments != null) { 
for (Int32 a = 0, 1 = appointments.Length; a < 1; att) { 


} 

} 

If you always design your methods so that they return arrays 
with zero elements instead of null, then callers of your methods 
will have an easier time working with them. By the way, you should 
do the same for fields as well. If your type has a field that is a 
reference to an array, you 
should always try to have 
the field refer to an array 
even if the array has no ele- 
ments in it. Allowing the 
field to be null will just 
needlessly complicate the 
use of your type. 


Creating Arrays with a Non-zero Lower Bound 
Earlier, I mentioned that it is possible to create and work with 
arrays that have non-zero lower bounds. You can dynamically cre- 
ate your own arrays by calling Array’s static CreateInstance method. 
There are several overloads of this method, but they all allow you 
to specify the type of the elements in the array, the number of 
dimensions in the array, the lower bounds of each dimension, and 


‘A Revolution ff 


On the pulse of time 
and technology 
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the number of elements in each dimension. CreateInstance allo- 
cates memory for the array, saves the parameter information in the 
descriptor portion of the arrays memory block, and returns a 
reference to the array. You can cast the reference returned from 
CreateInstance to a variable so that it is easier for you to access the 
elements in the array. 

The following code demonstrates how to dynamically create a 
two-dimensional array of System.Decimal values. 


// We want a 2-dim array [1995..2004][1..4] 

Int32[] lowerBounds = { 1995, 1 }; 

Int32[] lengths Si Seda}: 

Decimal[,] quarterlyRevenue = (Decimal[,]) 
Array.CreateInstance(typeof(Decimal), lengths, lowerBounds) ; 


The first dimension represents calendar years and goes from 
1995 to 2004, inclusive. The second dimension represents quarters 
and goes from | to 4, inclusive. The code in Figure 5 iterates over all 
the elements in the dynamic array. I could've hardcoded the array’s 
bounds into the code, which would've improved performance. But 
I decided to use some of System. Array’s GetLowerBound and Get- 
UpperBound methods for demonstration purposes. 


Fast Array Access 

Every time an element of an array is accessed, the CLR ensures 
that the index is within the arrays bounds. This prevents you from 
accessing memory that is outside of the array, potentially corrupt- 
ing other objects. If ever an invalid index is used to access an array 
element, the CLR throws a System.IndexOutOfRangeException. 

As you might expect, the CLR’s index checking incurs a perfor- 
mance cost. If you have confidence in your code and if you don't 
mind resorting to non-verifiable (unsafe) code, then there is a 
way to access an array without having the CLR perform its index 
checking (see Figure 6). To compile this code, you should use the 
following command line: 

csc.exe /unsafe UnsafeArrayAccess.cs 

After building this small application, running it produces the 
following results: 

1 
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Note that only five values should appear, but six values appear 
instead. This is due to a bug in the source code. In the for loop, the 
test expression should be x < |; not x <=1. This demonstrates how 
careful you must be when using unsafe code. 

By the way, if you use ILDasm.exe to examine the IL for Main, 
youll see the code in Figure 7, which I’ve commented. For com- 
parative purposes, here is a version that doesn’t use unsafe code: 

using System; 

class App { 

static void Main() { 
Int32[] arr = new Int32[] { 1, 2, 3, 4, 5 3s 


for (Int32 x = 0, 1 = arr.Length; x <= 1; xt+) { 
Console.WriteLine(arr[x]); 


Figure 8 Disassembled Code 


If you build this and use [LDasm to examine the IL code, youd see 
the code in Figure 8. 

It’s true that there is less IL code for the type-safe version. How- 
ever, it is the type-safe version’s Idelem instruction that causes the 
CLR to do index checking. The unsafe version uses the Idind.i4 
instruction instead; this simply obtains a 4-byte value from a 
memory address. Note that you can only use unsafe techniques to 
access an array of unmanaged types which includes SByte, Byte, 
Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Single, Double, 
Decimal, Boolean, and enumerated type, or a value type structure 
whose fields are any of the aforementioned types., 


4 


Redimensioning an Array 


Array’s static CreateInstance method allows you to dynamically 
construct an array when you don’t know at compile time the types 
of elements that the array is to maintain. It is also useful when you 
don’t know at compile how many dimensions the array is to have 
and the bounds of those dimensions. In the “Creating Arrays with 
a Non-zero Lower Bound” section, I already demonstrated how to 
dynamically construct an array using arbitrary bounds. The 
CreateInstance method can also be used to redimension an arbi- 
trary array (see Figure 9). If you build and run this application, 
youll see the following output: 


ces 
I 2 3400 
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Send questions and comments for Jeff to dot-net@microsoft.com. 


Jeffrey Richter is the author of Programming Applications for Microsoft Windows (Microsoft 
Press, 1999), and is a cofounder of Wintellect (http://www.Wintellect.com), a software education, 
debugging, and consulting firm. He specializes in programming/design for .NET and Win32. Jeff 
is currently writing a Microsoft .NET Framework programming book and offers .NET seminars. 
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“T had the opportunity the other day 
of ‘playing’ with InstallShield, and then it 
~ dawned on me what a great product I have in 
Wise for Windows Installer. It really does 
make installing our programs simple.” 


—Martin Hart, Memory Soft SL* 
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"You-know-who" would have you believe that 
they are the only ones you should think of when 
creating software installations. Our Wise for 
Windows Installer tool has convinced thousands 
of developers otherwise. Wise was the first to 
offer an installation product for Microsoft's 
Windows Installer service, first to support the 
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-~world-class technology and switch to Wise for 
Windows Installer. 


s Microsoft .NET Framework, and the first to 
- create 64-bit installations. 7 
2 Take a stand for ease-of-use, reliability, and 


Want to know the other reasons why you 
should switch to Wise? Get the switch kit and 
find out at www.switchtowise.com or order 
today at 800-554-8565. 


*Unsolicited testimonial from a satisfied Wise Solutions customer. 
Full text of this quote can be found at www.wisesolutions.com 
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Software installations made easy” 


The Continuing Challenges of XML Web Services 


DON 


n spending time with literally thousands of developers over the 
past eight years, I have noticed that there are two types of devel- 
opers out in the wild: those who prefer to work at start-ups and 
those who prefer to work at large and established companies. Hay- 
ing just spent eight years building a start-up into an established 
company, I can't honestly say which type of organization I prefer. I 
can state wholeheartedly that in terms of the technologies I work 


with, I definitely prefer “start-up” technologies to those technolo- | 


gies that are considered to be well established. 

Technologically speaking, Iam a textbook entrepreneur. Once a 
technology stabilizes, I want to move onto the next frontier. Ulti- 
mately, that’s why I stopped doing serious COM work. That’s also 
why the Common Language Runtime (CLR) doesnt do it for me. 
Dont get me wrong—I love using the CLR. After exploring almost 
every nook and cranny I could find, I still think that the CLR is a 
fantastic piece of technology and recommend it to all my friends 
and colleagues. That stated, once Visual Studio’ .NET ships, hun- 
dreds of thousands of developers will come to depend on the CLR, 
which means that changes and innovation will be more evolution- 
ary than revolutionary. 


In contrast to COM and the CLR, XML is still a fairly broad | 


canvas upon which developers get to repaint the world every six 
months. To some, this marginalizes XML as a trendy technology 
fad that will implode under the weight of its own hype and/or 
instability. To others, this represents an opportunity to recast a 
problem domain using broadly accessible tools and techniques. 
Needless to say, I fall firmly into the latter camp. 

Working with XML and Web Services is not without its chal- 
lenges. To that end, this month's column outlines what I believe to 
be the biggest challenges facing XML Web Service practitioners 
and plumbers at the beginning of 2002. 


Specification Convergence (or lack thereof) 

Because XML is a vendor-neutral technology, it is largely speci- 
fication-driven, with the W3C acting as the home of all core XML 
specifications. When all of the specifications are stable and com- 
plete, this is a good thing, as every vendor can build plumbing 
against a common set of protocols, knowing that cross-vendor 
interoperability is at least attainable—if not certain. However, when 
all of the requisite specifications are not complete, developers are 
forced to choose between hand-rolling implementations of speci- 


fications still in progress or waiting until their platform vendor | 
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catches up. Fortunately, most (but not all) of the more complex 
XML technologies are fully specified, which means that implement- 
ing an occasional specification by hand is not terribly difficult. 

This column was written as 2001 came to a close. It was actually 
a very good year for XML specifications. By the end of 2001, the 
three specifications that comprise the base data model for XML 
had achieved full recom- 
mendation status (this is 
the’end of ‘the’ lme-for.a 
W3C specification and a 
critical step towards stabil- 
ity and interoperability). 
These specifications are 
XML 1.0 second edition, 
the XML Information Set, 
and XML Schemas. 

The second edition of 
XML 1.0 (see http://www.w3.org/TR/REC-xml) was an editorial exercise 
that incorporated fixes for roughly three years worth of errata 
reported against the 1998 version of the specification. 

The XML Information Set (Infoset) specification (see http:// 
www.w3.org/TR/xml-infoset) was finally advanced to full recommenda- 
tion status in 2001 after roughly two years in W3C purgatory. The 
Infoset describes the abstract data model that “is” 


is’ an XML docu- 
ment. The Infoset is important because it identifies what is and is 
not important in an XML document. For example, the Infoset 
indicates that there is no semantic difference whatsoever between 
the following three elements: 

<customer></customer> 


<customer/> 


<customer ></customer> 


Most newer XML technologies are defined in terms of the In- 
foset, not the underlying XML 1.0 syntax. That means that very 
few XML technologies retain the differences between these three 
representations of essentially the same element. 

By far the most important of the three data model specifications 
is XML Schema (see http://www.w3.org/TR/xmlschema-1). XML Schema 
advanced to full recommendation status in May 2001 (see Figure 1) 
and vendor support has been getting better each month since then. 
XML Schema provides a type system for the XML Infoset, making 
XML much more suitable for integrating software components 
and applications that rely on strong typing. 


february2002 129, 


130 msdnz 


XML Schema provides three fundamental fea- 
tures, all of which are heavily used by Web Ser- 
vice technology. First, XML Schema defines a 
type system for simple value types such as double, 
boolean, and so on. Because XML is inherently a 
text-based data representation, this type system 
distinguishes between the abstract value space 
of a type and Unicode-based lexical representa- 
tions. Furthermore, XML Schema defines a 
strongly typed way to look at XML-based infor- 
mation called the post-schema-validation Infoset 
(PSVI). The PSVI is a type-aware version of an 
XML Infoset in which the type affiliation of each element and 
attribute is available to higher-layer technologies and applications. 
The following elements show why these features are important: 


Type-aware 
Data Model 


LEO ORSON 
€ 


# 


Syntax-free 
Data Model 


Portable 
Transfer 
Syntax 


<age>0000200</age> 
<age>200.00000</age> 
<age>2e2</age> 


At the basic Infoset level, these three elements are different since 
each of the elements has a different number of children (seven, 
nine, and three, respectively) and few of the children of one ele- 
ment match the children of another. Assuming the XML Schema 
type system and PSVI, the three elements may be considered 
equivalent provided that the age element is affiliated with the built- 
in type double. 

Despite the differences in the previous three elements, most 
humans would intuitively feel they are equivalent. This is because 
humans can often infer type based on lexical patterns. To allow 
XML-based software to infer type, XML Schema provides a schema 
definition language (often referred to as XSD) for indicating the 
type affiliation of elements and attributes. The schema definition 
language is where most developers start focusing; however, the 
type system and PSVI are at least as important to modern XML- 
based architectures. 

Though work on the XML Schema specification is now fin- 
ished, by no means is the W3C done churning out new specifica- 
tions. In fact, the presence of XML Schema actually makes at least 
one existing technology obsolete: XPath. 

XPath was defined prior to either the Infoset or XML Schema. 
To avoid dependencies on XML syntax, XPath defined its own 
data model that was similar to the Infoset. Moreover, XPath de- 
fined a very rudimentary type system of its own that had exactly 
four types: boolean, number, string, and node-set. Unfortunately, 
since XPath was defined prior to XML Schema, the type of a given 
attribute or simple element was always string. To treat attribute or 
element values as boolean or number, you needed to explicitly 
cast. For example, consider the following XML document: 


<add> 
<a>200</a> 
<b>200.0</b> 
</add> 


Because XPath considers all element and attribute values to be 
of type string, the following XPath expression would result in the 
boolean value false. 

Jadd/a = /add/b 
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To perform numeric comparison, an explicit 
conversion is required: 

number(/add/a) = number(/add/b) 

If XPath had been written against the PSVI, the 
conversion would not be necessary. To address 
this, version 2.0 of XPath is now being defined 
in terms of PSVI. Because XSLT is a heavy user 
of XPath, XSLT 2.0 will also gain type-aware- 
ness. Unfortunately, XPath 2.0 and XSLT 2.0 
won't be complete until at least 2002. 

XSLT is one way to process XML-based in- 
formation. However, it is by no means the only 
way. One emerging technology that provides an alternative to XSLT 
is XML Query. XML Query has become the new hot technology in 
core XML, and the XML Query working group is producing work- 
ing drafts faster than most developers can read them. Like XSLT, 
XML Query allows you to specify literal result elements that are 
annotated with processing hints. However, XML Query uses more 
familiar SQL-like constructs rather than XPath expressions. For 
example, the following XSLT fragment 


SSS OSOIS SIDS NSAI EUS SISSIES SITS DS SPS DISPEL DS LDA TEASED 


a 


os 


<xsl:template name="bob"> 
<bib> 
<xsl:for-each select= 
"document ("books.xml")/bib/book[pub="Wiley"] "> 
<book year="{@year}"> 
<xsl:copy select="title" /> 
</book> 
</xs1:for-each> 
</bib> 
</xsl:template> 


could be rewritten in XML Query as follows: 


<bib> 
{ 
FOR $b IN document("books.xml")/bib/book 
WHERE $b/pub = “Wiley” 
RETURN 
<book year={ $b/@year }> 
{ $b/title } 
</book> 
} 

</bib> 
Note that the XML Query processing model remotely resembles a 
SQL SELECT statement. 

While some Web Services will be written exclusively in XSLT or 
XML Query (especially once the specifications are finished), many 
existing implementations use alternative, ad hoc implementation 
techniques. This is a feature, as having one true way to build XML- 
based applications is still far off. However, for these implementa- 
tions to interoperate, some common metadata format is needed to 
describe the operations that can be performed on a Web Service. 
Its WSDL to the rescue. 

WSDL, or Web Services Description Language, augments the 
XML Schema language by defining operations as typed message 
exchanges. Describing the format of the messages to be exchanged 
is a solved problem, service XML Schema gives you a perfectly 
reasonable way to describe XML-based information. WSDLs con- 
tribution to XML Schema is that it defines a type system for typed 
endpoints or services. These endpoints/services implement one or 


more port types. A port type consists of one or more operations. 
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Celebrating 10 years of Tech-Ed 


This year, Tech*Ed ts better than ever, with even more 
information, more hands-on training, and more tools for 
building solutions using Microsoft platforms - including 
the newly released version of Visual Studio®. NET. Join us, 
and start building integrated solutions faster. 


Rational 


the e-develepment company 


© 2002 Microsoft Corporation. All Rights Reserved. Microsoft and Visual Studio.NET are registered trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the respective trademarks of their respective owners. 


A special issue of one of the greatest 
computer magazines EVER is coming soon... 


BYTE was born when 
and were 
still groovy. 


It was the beginning of 
the personal computer 
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An operation is a named pair of messages, one containing the 
input to the operation and the other containing the results. WSDL 


operations correspond roughly to a CLR method; WSDL port | 
types correspond roughly to a CLR interface. A WSDL service is | 
not the equivalent of a CLR class—rather, the closest analogue in | 
_ approach has little use for SOAP section 5, instead choosing the 


the CLR is a named singleton. 


Conceptually, WSDL is a more than reasonable solution for de- | 
scribing Web Services. However, at the time of this writing, the 
| than in the Microsoft’ .NET Framework. The .NET Framework 
_ includes two XML serialization engines: System.Runtime.Serial- 


current version of WSDL is version 1.1. WSDL/1.1 is simply a 
W3C note and has yet to endure the W3C process. Additionally, 


field experience with WSDL has revealed a number of issues that | 
need to be addressed in order to achieve compliance with other | 
technologies, most notably XML Schema. Again, these two factors | 
: correct implementation of SOAP section 5 on the planet; however, 


illustrate how specification churn is far from over. 


The technologies just discussed are all at some stage in the W3C | 
process, which means that you can track their progress and par- | 
ticipate in their final form. Beyond these technologies, there are | 
hosts of vendor-specific technologies that are being churned out 
_ XML Schema constructs than System.Runtime. Serialization; how- 


by vendors of all sizes and shapes, including Microsoft. While 


some of these technologies may eventually be submitted to the | 
_ taining object references. 


W3C or other standards bodies, they are far from final, which 
means that adapting to the current state-of-the-art may require 
that you write significant parts of the plumbing yourself until the 
vendors can completely hide the details in their platforms. 


Battle for World (Type System) Domination 


The Simple Object Access Protocol (SOAP) was defined prior 
to the advent of XML Schemas. The original goal of SOAP was to 


marshaling format for in-memory object graphs and C-style 


data structures that would act as requests or response messages _ 


between the various components. 


Because XML Schemas did not exist when SOAP was first de- 
veloped, the original SOAP authors defined a type system for rep- 
resenting strongly typed information in XML. That type system | 
evolved considerably over the three years of SOAP’s life prior to | 
W3C, eventually becoming known as section 5 due to its location — 
in the SOAP/1.1 specification (http://www.w3.org/TR/SOAP). SOAP sec- | 
tion 5 had one simple charter: codify how to serialize strongly — 
typed data structures into XML. The strongly typed data struc- : 
tures the authors had in mind were primarily object graphs suchas | , ice a Ee 
those found in the CLR or the Java VM. If all you care about is _ ee eipria oe  acs 
serializing CLR or Java object graphs into XML, SOAP section 5 | 
provides a concise format that retains full fidelity with both the | 


CLR and Java type systems. 


SOAP section 5 assumed an object-centric view of the world. In | 
particular, it assumed that developers couldn't care less about the | 
underlying XML format being used. Rather, SOAP section 5 as- | 
sumed that most implementations would derive the XML format | 
based solely on the type definitions used by the “local” program- — 


cr 


world view in two to three years. In fact, there are a growing num- 


_ ber of developers who believe that XML, not objects, will be the 


dominant type system for Web Services. This world view depre- 
cates objects as an implementation detail and elevates XML Schema 
as the dominant type system for all messages. This XML-centric 


broader XML Schema data model for use in all message exchanges. 
Nowhere is the tension between the two worlds more evident 


ization and System.Xml Serialization. The former assumes that 
the CLR type system is the dominant system, as shown in Figure 2. 
System.Runtime.Serialization is arguably the most complete and 


it cannot cope with arbitrary XML Schema types. 

In contrast, System.Xml.Serialization assumes that the XML 
Schema type system is the dominant system, as shown in Figure 3. 
System.Xml.Serialization can handle a much broader range of 


ever, it cannot handle arbitrary CLR objects, especially those con- 


The two serializers exist to service the two world views just 
described. Developers with an object-centric viewpoint will deti- 
nitely use System. Runtime.Serialization. Developers with an XML- 
centric view would prefer System. Xml.Serialization. However, XML 
purists are likely to eschew any serialization engine, since they are 


- bound to have fidelity loss due to the inherent differences between 
| the CLR type system and the PSVI. 

build a Web-friendly network protocol for integrating compo- | 
nents over the Internet. XML was becoming the data format of | Messages versus RPC 
choice for Web-based applications, so SOAP used XML as a | 


_ be clear, Web Services are always built based on the exchange of 


This debate is often confused with the previous discussion. ‘lo 


messages. The type system of those messages may be object-based 
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ming technology (such as CLR or Java). This world view reduces | 


XML to second-class status, and may or may note the dominant | Figure 3 System.XML.Serialization 


House of Web Services february2002 133 


(a la SOAP section 5) or XML Schema-based. Once the type sys- 
tem of the messages is decided, the next battle is whether message 
exchanges and remote procedure calls (RPCs) are the same. 

The messaging versus RPC debate has gone on for decades and 
shows no sign of stopping anytime soon. The arguments on both 
sides can be reduced to distinguishing the atoms from the mol- 
ecules. The messaging view of the world defines the message as the 
atom and elevates messages to first-class status. In a messaging- 
oriented world, RPC is simply a particular message exchange pat- 
tern in which a request message triggers the generation of a response 
message destined for the sender of the original request. Message 
purists tout that this is but one message exchange pattern and that 
by viewing the world in terms of RPC, no other patterns are obvi- 
ous or even possible. 

The RPC-centric view acknowledges the existence of messages, 
but tends to view the overall operation as the atom. To support 
some of the flexibility of messaging, most modern RPC systems 
support asynchronous invocation and one-way operations. Asyn- 
chronous invocation is largely a local language binding issue and 
has little to no impact on the messages exchanged on the wire. In 
contrast, one-way operations have no response message. RPC pur- 
ists argue that any system designed around a messaging paradigm 
could be just as easily designed around one-way RPC calls. 

An interesting technology that lives at the boundaries of this 
debate is the CLR’s transparent proxy. The transparent proxy exists 
for one purpose: to convert a method call into a message exchange. 
The transparent proxy is an object in memory that supports a 
particular CLR type. When a method is invoked against the trans- 
parent proxy, the CLR converts the call stack into a request mes- 
sage. This request message is then dispatched to a buddy object 
(known as the real proxy). The real proxy is expected to return a 
second message containing the results of the operation. When the 
real proxy returns the result message, the CLR ensures that the 
results are reflected on the call stack presented to the transparent 
proxy. As shown in Figure 4, the CLR provides a similar facility for 
converting a request message back into a stack frame in order to 
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Figure 4 Transparent Proxy 
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dispatch the call generically to a target object. The transparent 
proxy facility is used by at least one Web Service implementation 
that ships with the .NET Framework. 

SOAP and Web Services have simply resuscitated the messaging 
versus RPC debate. Whether or not the debate will be resolved 
remains to be seen. However, the fact that the underlying message 
format is XML allows a larger number of developers to experiment 
with both approaches and come to their own conclusions. 


Libraries versus Languages 

Making XML accessible to programmers is actually a very big 
challenge. To date, there have been two fundamental approaches: 
libraries and languages. Library-based approaches are based on a 
class library or framework that is written in a traditional program- 
ming language for use from a traditional programming language. 
Examples of library-based approaches include SAX, Apache's 
Xerces and Cocoon, and the .NET Framework’s System.Xml li- 
brary. Language-based approaches typically coin a new program- 
ming language designed to process XML-based data. XSLT and 
XML Query are examples of the language approach. 

Both library and language-based approaches have their pitfalls. 
Library-based approaches typically need to address the mismatch 
between the XML type system and the type system of the underly- 
ing language or programming environment. Since many Web Ser- 
vices are expected to use other Web Services, this approach can 
result in a significant amount of type conversion as the response 
from one service is converted from XML into local types only to 
then emit XML as the upstream response. Additionally, because 
library-based approaches typically have little integration with the 
type system of the host programming language, many errors that 
could be caught at compile time become runtime errors. 

Proponents of language-based approaches believe that by cou- 
pling the programming language to the underlying XML type 
system, not only can errors be discovered at compile time, but also 
more information is available to produce better code. The down- 
sides of a language-based approach are numerous. For one, pro- 
gramming languages are far more personal than libraries; every 
developer has their own sense of aesthetics that need to be ad- 
dressed. Additionally, producing a new language implies the de- 
velopment of a new compiler and debugger, both of which are 
fairly significant tasks. : 

The language versus library debate is analogous to the object 
versus XML debate. Developers who view the world as object- 
centric are likely to prefer library-based solutions. Developers who 
have an XML-centric view are likely to prefer a language-based 
solution. Once XML Query and XSLT 2.0 are finalized, developers 
will have a clear choice between the two. 


Poor Support for Streaming Architectures 

The DOM has held back XML development more than any 
other technology I know of. The DOM is an in-memory cache for 
XML documents. The DOM is intuitive. The DOM is easy to use. 
The DOM lets you forget that the underlying XML is likely com- 
ing from somewhere else, and that is its fundamental problem. 


XML-based applications such as Web Services are very I/O 
bound. Web Service requests and responses are I/O. Calls to data- 
bases or subordinate Web Services are also I/O. The DOM ignores 
all of this. To DOM-based applications, I/O is an afterthought that 
happens before and/or after the interesting processing takes place. 

The argument against the DOM is similar to the argument 
against static cursors in ADO. In both cases, an in-memory cache 
must be populated in order to work with the underlying data. In 
both cases, the entire image winds up consuming memory by the 
time the I/O is complete, which can limit the scalability of server- 
side applications. In both cases, there is an asynchronous read/ 
load operation, but few developers take advantage of it, largely due | 
to COM threading weirdness. | 

The trend in the last two years has been to forgo the DOM in 
favor of streaming interfaces. SAX is the canonical example of a | 
streaming interface. The .NET Framework’s XmlReader is a varia- | 
tion on SAX that also is based on streaming. Streaming interfaces _ 
are analogous to forward-only/read-only firehose mode data ac- | 
cess techniques. In both cases, the underlying plumbing only re- | 
tains as much information as is needed to satisfy the next read | 
request. Once a portion of the data has been read, the underlying | 
plumbing can freely discard the buffered information. This can | 
have a tremendous impact on resource consumption, especially 
for large chunks of data. | 

Despite the popularity of SAX and XmlReader, the entire world | 


hasnt jumped on the streaming bandwagon. In particular, tech- 
nologies such as XML Query and XPath (and, by inference, XSLT) 
support backward traversal, which makes using these technolo- 
gies in streaming contexts _ 
difficult. It remains to be 
seen if the W3C has the 
cycles or the will to develop 
a streaming-friendly pro- 
cessing model and lan- 
guage in the mold of XSLT 
or XML Query. Until that 
happens, developers work- 
ing with large volumes of 
XML need to do a signifi- 
cant amount of manual labor to avoid killing performance. 


Three Views of Discovery 

First, let’s set the record straight. XML is not self-describing. If 
an arbitrary XML document falls from the sky into your lap, there 
is very little you can do with it. The fact that the element and 
attribute names are part of the serialized form does not make XML 
self-describing. If it did, then I challenge you to tell me what the 
following document means: 

<draw /> 
Without context, element and attribute names are meaningless. 
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A lot of attention is paid to discovery. Unfortunately, the term 
itself is vague. In terms of Web Services, there are ultimately three 
forms of discovery: type discovery, endpoint discovery, and se- 
mantic discovery. Let’s look at each of these individually. 

Type discovery is a development time phenomenon. As a devel- 
oper is writing a program, the types that will be used by the pro- 
gram need to be accessible to the developer as well as to the 
underlying build environment. Discovering these types means 
finding the metadata for the types. In the world of Web Services, 
WSDL and XSD are the metadata formats of choice. Web Service- 
aware build environments can consume WSDL and/or XSD and 
make the underlying types available to your program. 

Type discovery focuses on where the WSDL/XSD can be found 
at development time. Finding WSDL/XSD is like finding C header 
files or COM type libraries. If someone gives you a file and says 
“here's what my stuff looks like—party on,’ then you are set. Of 
course, with WSDL/XSD, the file is likely to be a URL that points to 
a program that generates the metadata on the fly, but ultimately, as 
far as your build environment is concerned, it’s just another file. 

There are various conventions for finding WSDL/XSD in cases 
where you do not already have a URL to a Web Service's metadata. 
Web Services written using the .NET Framework all support the 
“WSDL query string, which tells the plumbing to emit the WSDL 
for the Web Service. Other specifications such as DISCO and WS- 
Inspection allow you to send a well-known request to the root 


URL of a Web server and get a list of all WSDL documents avail- 
able from that server. For the lion's share of type discovery applica- 
tions, this is more than sufficient. 

The second form of discovery that bears discussion is endpoint 
discovery. In general, it is dangerous to bake the endpoint address 
of a Web Service into your application. Between dot-com failures, 
DNS hijacking, and general deployment flexibility, placing a level 
of indirection between your program and the Web Service address 
is generally a good thing. This is the role of endpoint discovery. 

Endpoint discovery typically happens at deployment time, when 
an application is installed. Endpoint discovery can also happen at 
runtime, either as the application initializes or, in the face of Web 
Service failure, when a different server machine must be selected. It 
typically focuses on finding new implementations of known port 
types. This is similar to finding classes that support a given inter- 
face. WSDL allows multiple services (endpoints) to implement a 
given port type, which certainly makes this sort of polymorphism 
possible. However, the WSDL type system does not distinguish 
between endpoint address and implementation type, which means 
that not all implementations of a port type are semantically inter- 
changeable. However, in constrained scenarios, WSDL-based so- 
lutions can be made to work in this context. 

In a WSDL-based world, endpoint discovery is largely a matter 
of finding implementations of a known port type. At the time of 
this writing, both WS-Inspection and UDDI version 2 had rudi- 
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mentary support for this style of discovery, although that style of — 


discovery is not the focus of either technology. 

Finally, the third form of discovery to be discussed is semantic 
discovery. Conveying meaning in machine-readable form is an 
open research area that has yet to produce technically and com- 
mercially viable solutions. At the time of this writing, semantics are 
conveyed in human-readable form (that is, documentation) and 
programmers are paid to understand the semantics of a given 
piece of code or type and use those semantics in their own pro- 


grams. It is important that type discovery not be confused with — 


semantic discovery. Types do not convey semantics—rather, they 
give us aname that can be used in both programs and documenta- 
tion. Both WSDL and XSD provide well-known locations to pro- 
vide semantic descriptions, however, in both technologies, these 
descriptions are simply human-readable prose not meant for ma- 
chine interpretation. For the near-term future, that is as close to 
semantic discovery as we are likely to get. 


Parsers 

XML’ greatest strength is often its greatest weakness. The fact 
that XML is a text-based data representation that can be easily 
manipulated using text editors such as Notepad or Emacs makes it 
immediate and accessible. Unfortunately, to make XML authorable 
by a wide variety of individuals and tools, the XML 1.0 specifica- 
tion is filled with details and special-case exceptions that make the 
efficient parsing of XML challenging, to say the least. To keep 
parser writers honest, OASIS publishes a test suite of XML docu- 
ments that are used for conformance testing that contain many of 
these special-case exceptions. The art of parser development is 
passing the OASIS test suite without totally killing performance. 

Frustrated with the complexity of parser development, Don Park 
and Simon St. Laurent proposed a subset of XML called Simple 
Markup Language (SML). SML was a proper subset of XML— 
that is, all SML documents were legal XML, but not all XML docu- 
ments are legal SML. SML was developed to make parser 
implementation approachable to mere mortals. SML tried to iden- 
tify the subset of XML that was needed for software-generated 
XML, not human-generated XML. 

SML was an ad hoc effort that began on the XML-DEV mailing 
list. Canonical XML (see http://www.w3.org/TR/xml-c14n) is a more for- 
mal effort that originated from the W3C. Canonical XML is a 
subset that was designed to eliminate many of the redundancies in 
XML 1.0. Many (but not all) of the aspects of SML are present in 
Canonical XML. Canonical XMUs primary advantage is that it is 
“blessed” by the W3C and is likely to gain widespread support. 

A side effect of subsetting XML with Canonical XML is that 


i 
i 


parsers (and processing in general) can go considerably faster when _ 


certain XML “features” are assumed to be absent. Consider finding | 


an element with an attribute named moniker whose value is Don. 
You could use simple string matching via strstr: 


const char *FindDon(const char *pszDoc) { 
const char *pszPattern = "moniker=\"Don\""; 
const char *psz = strstr(pszDoc, pszPattern); 
Thx psa) at 
psz = strrchr(psz, ‘<'); + 


} 
return psz; 


} 


Unfortunately, this technique would miss the following elements 


<dude moniker='Don' /> 
<dude moniker="D&x6F;n" /> 


both of which satisfy the condition of having a moniker attribute 
whose value is Don. Had the data been encoded as Canonical 
XML, neither of these two elements would have been legal, as their 
Canonical XML encoding would have looked like this: 


<dude moniker="Don" /> 


It remains to be seen whether XML parsers will be tuned to 
Canonical XML, and if they are, how much performance benefit 
could be gained by the simplification of the underlying format. 

In many respects, Canonical XML is similar to the Infoset in 
that both identify what is and is not important in an XML docu- 
ment. The difference is that Canonical XML is defined simply by 
subsetting XML 1.0; that is, Canonical XML is itself a machine- 
readable format, not simply an abstract data model. 

A related area of research is alternate encodings for XML-based 
information that are not text-based. The first such effort was 
WBXML, which is used by WAP to send XML-based information 
to cellular phones. WBXML suffers from coming too early in the 
development of XML, and is not broadly used outside of the wire- 
less world. Again, discussions on the XML-DEV mailing list re- 
cently steered towards defining a new binary format for XML-based 
information. Whether or not the W3C will pick up such an effort 
remains to be seen. At the very least, this technique is used exten- 
sively today within controlled environments, such as when XML- 
based information is passed from one component to another in 
memory, In these scenarios, XML-based information is usually 
passed via a SAX pipeline or a DOM rather than as an array of 
octets that must be reparsed using an XML parser. Evolving this 
approach to an in-memory data representation is not that far 
fetched and would likely yield performance benefits by eliminat- 
ing the massive number of virtual method calls inherent in SAX 
and DOM-based systems. 


Lack of Unified Authentication 


No discussion of the challenges of Web Services would be com- 
plete without a discussion of authentication. At the time of this 
writing, there is no single authentication technique that is sup- 
ported by every major vendor. Microsoft has one solution, Pass- 
port, which is likely to be supported across all Microsoft-based 
Web Services and plumbing. However, there are numerous other 
solutions being pitched by competing vendors and open source 


_ advocates. Unfortunately, in the absence of a universal and ubiqui- 


tous authentication technique, developers fall back on proprietary 
ad hoc solutions. Many hand-rolled authentication techniques are 
insecure and easily hacked, making the need for a universal au- 
thentication mechanism all the more pressing. 

Send questions and comments for Don to housews@microsoft.com. 


Don Box spends most of his time working with component technologies, lately focusing on XML . 
and Web Services. Don’s latest book, Essential .NET, is due out this year from Addison-Wesley. — 
Find out more about Don at http://www.donbox.com. 
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WHEN I DECIDED TO WRITE a 
book to help VB 6.0 programmers 
learn VB .NET, I knew what I 
did NOT want to write. I didn’t 
want to just rehash the MSDN 
documentation. And I didn’t want 
to review material that any 
intermediate to advanced VB 
programmer already knows. That 
left me to focus on three areas that 
I knew would be crucial for learning VB .NET. The 
strategies—how and when to deploy .NET. The concepts— 
those new to VB programmers both in terms of language 
and in terms of the .NET Framework. And the code—the 
nitty-gritty details of how and why the language has 
changed. Oh yes, and I wanted it to be as fun and 
entertaining as a hard-core technical book can be. I think 
you ll be pleased with the results. 


Dan Appleman 
San Jose, California 


I STARTED WORKING WITH VISUAL 
BASIC .NET when it was a “tech- 
nology preview’—long before it 
was in beta. I immediately became 
convinced that it was not a VB 7.0, 
but rather the first truly new 
language in the BASIC family. This 
in turn meant that all earlier books 
on Visual Basic (including my own) 
could not be revised—VB .NET 
needs a whole new approach. And that is what I try to 
provide in my book. But given the amazingly rich .NET 
Framework, I also needed to keep the book a manageable 
size. My idea was to concentrate on the techniques you need 
to master rather than the Framework. I feel that if you master 
the essential techniques, you can use the more specialized 
Framework-specific books effortlessly. 


Gary Cornell 
Berkeley, California 
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Getting a Class Name, ImgView Revisited, GetModuleFileName, and More 


PAUL DILASCIA 


I have two classes, Derived! and Derived2, that are derived © 
from a base class. In the constructor of the base class, I would | 

like to get the name of the class for which this object is being | 
created—that is, Derived] or Derived2. Is it possible to get the © 
name of the class as a string? : 
Nilesh Padbidri | 


At short answer is: no. A base class doesn’t know anything 
about what class it’s derived from—and it's a good thing, too. 
You might think you could solve the problem by inventing a vir- 
tual function GetClassName 


class Derivedl : public Base { 
virtual string GetClassName() { 
return "Derivedl"; // or Derived2 
} 
i 


and call GetClassName from the Base constructor. But this won't 
work because in the constructor Base::Base, the vtable for De- 
rived! isn't established yet. That is, the object doesn't officially 
become an instance of Derived1 until the constructor Derived 1:: 
Derived! begins. In pseudocode, the Derived! constructor looks 
something like this: 


Derivedl::Derivedl(...) 
{ 
// compiler-generated: 
Base::Base(...); // call base ctor 
vtbl = Derivedl_vtbl; // set up vtbl pointer 


// rest of your ctor 
} 


When the Base class constructor runs, the vtbl is still the vtbl for 
the Base class. This issue comes up repeatedly in different ways and | 
situations. Why does C++ do it this way? Because it isn’t logical to | 
let you call a Derived! function—virtual or otherwise—until the — 
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Derived1 constructor has initialized the object. The object doesn't | 

become a derived object until the derived constructor runs. : 
So, what can you do? If you want the class name in the Base | 

constructor, the only way to get it is to pass it as an argument. 


class Base { 
Base(string sClassName,...); 


Derivedl::Derivedl(...) : Base("Derived1”, ...) 
{ 
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}; 
In MEC, this sort of thing is handled a little more complicatedly | 


(hey, am | allowed to coin a word here?) using CRuntimeClass. 
CRuntimeClass represents—what else?—a runtime class. For ev- 
ery class you or MFC declares with DECLARE_DY NAMIC, DE- 
CLARE_DYNCREATE or DECLARE_SERIAL, you get a static 
CRuntimeClass instance to represent the class. In fact, pretty much 
the only purpose of DECLARE/IMPLEMENT_DYNAMIC is to 
set this up. 


class CDerived : public CBase { 

// DECLARE_DYNAMIC(CDerived) expands to: 
protected: 

static CRuntimeClass* _GetBaseClass(); 
public: 

static CRuntimeClass classCDerived; 

virtual CRuntimeClass* GetRuntimeClass() const; 
} 


DECLARE_DYNAMIC declares three things: a static function 
to get the base class run- 
time class (CRuntimeClass 
for CBase), a static CRun- 
timeClass instance called 
classCDerived—the name 
of this object is the word 
“class” followed by the class 
name—anda virtual func- 
tion, GetRuntimeClass, 
that returns a pointer to it. 
IMPLEMENT_DYNAMIC 
implements all this. 


// IMPLEMENT DYNAMIC(CDerived,CBase) 

// expands to: 

CRuntimeClass* CDerived:: GetBaseClass() { 
return RUNTIME CLASS(CBaseClass); 

} 


const CRuntimeClass CDerived::classCDerived = { 
"CDerived" , .sizeon(class, Cherived),......: 
savieanics CDerived::GetRuntimeClass() const { 
return RUNTIME _CLASS(CDerived) ; 

} 

RUNTIME_CLASS is yet another macro. It expands to &C- 
Whatever::classC Whatever. So, for example, there's a classCWnd, 
classCDialog, classCListCtrl, and so on—the CRuntimeClass ob- 
jects for these classes. There's exactly one CRuntimeClass for every 
MFC class (those that use DECLARE/IMPLEMENT_XXX). The 
CRuntimeClass holds the name of the class, its size, schema num- 
ber (for serialization), and other meta class stuff. The way to get the 


CRuntimeClass for a given class is to hardcode RUNTIME_ 
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Figure 1 Getting the Class Name 


CLASS(CSomeClass), in which case you have to know the class 
name at compile time, or you can call the virtual GetRuntimeClass. 
But even that won't get you the runtime class for the derived class 
from within the base constructor, because, like I said earlier, the 
vtbl is still the base vtbl and GetRuntimeClass calls Base::Get- 
RuntimeClass (see Figure 1). 

Once you have a pointer to the CRuntimeClass, you can get the 
class name from CRuntimeClass::m_lpszClassName. CRuntime- 
Class is a struct, not a class, so all its members are public. 


I’m a newcomer to MFC and am working on a project to 
display photos. I’ve read through the code project Img View 
from your October 2001 column (http://msdn.microsoft.com/msdnmag/ 
issues/01/10/c/c0110.asp) and I find it is excellent and perfect as a 
foundation for my project. However, I couldn't find the class 
CArchiveStream or the file Afxpriv2.h on the MSDN” Web site. 
Would you please tell me the purpose and definition of the 

CArchiveStream? 
Sam Ng 


Well, first of all ’'m happy my code was “excellent and perfect” 

for your project—I guess that means there were no bugs and 
therefore I wrote it. (Hey, how much did we pay this guy?) As for 
afxpriv2.h, MFC has a number of private definitions and classes 
declared in afxpriv.h. afxpriv2.h is a secondary file included by 
afxpriv.h, so there’s no need to include it directly. The classes in 
these files are neither documented nor officially supported; how- 
ever, they're unlikely to change any time soon, so many program- 
mers use them anyway. Just be advised that the Redmondtonians 
are free to change this stuff in future releases of MFC, if ever there 
are any. All of which is merely a longwinded way to say: go ahead 
and use whatever goodies you find in afxpriv.h, including C- 
ArchiveStream. 

And now to your question: what exactly does CArchiveStream 
do? Answer: itimplements an [Stream interface based on CArchive. 
In other words, suppose you want to use some COM interface that 
requires [Stream, but you either don’t have a clue what IStream is 
and/or you weep at the prospect of implementing QueryInterface, 
AddRef, Release, Read, Write, and nine other functions even if all 


they do is return E_NOT_IMPLEMENTED. Well, there's no 
need to weep; CArchiveStream will save your day. It provides the 
[Stream you need, using your CArchive to supply the underlying 
data stream. 


CArchive ar; // your archive 

CArchiveStream arstm(ar); 

HRESULT hr = 
SomeCOMFunctionThatNeedsAStream(&arstm) ; 


Pretty easy, eh? In most cases you don’t have a CArchive, but a 
CFile. No problem, it’s easy to create an archive from a file. 


CFile file; // your file 
CArchive ar(&file); // now it's a CArchive 


Would that COM be always so easy. 


I’m trying to find the FileVersion from the VersionInfo re- 
source of a bunch of DLLs that I’m putting together for an 
SDK. I don’t want to hardcode the DLL file name into the call for 
::GetModuleHandle since I want to reuse the common routine for 
all the DLLs I have. Is there a way to get the name of the current 
DLL where an exported function lives, from code in the exported 
function? Or can I get the instance handle of the DLL? 

Vince Paragano 


eee is the function you want; it gets the 
name of amodule—DLL or EXE. GetModuleFileName takes 
an HINSTANCE and a buffer in which to put the name. You can 
call GetModuleFileName with a NULL instance handle, but then 
it returns the name of the running process (EXE), not the DLL. To 
get the name of the DLL, you need its instance handle. 

If youre using MFC, you can get the instance handle from Afx- 
GetApp()->m_hInstance. AfxGetApp returns a pointer to the cur- 
rent global application object (DLL object in the case of a DLL); 
m_hInstance is the instance handle. 


char buf[MAXLEN]; 
::GetModuleFileName(AfxGetApp()->m_hInstance, buf, sizeof(buf); 


If youre not using MFC, you'll have to save the HINSTANCE 
yourself somewhere as a global, in DilMain, when your DLL first 
starts up. | 


// module instance handle-global variable 
HINSTANCE h_hInstance; 
BOOL DIIMain(HINSTANCE hinst, DWORD dwReason, ...) 


{ 
if (dwReason == DLL_PROCESS_ATTACH) { 
g_hInstance = hinst; // save it 


} else if (dwReason == DLL_PROCESS DETACH) { 
g_hInstance = NULL; // good idea 


I am using a class that contains a static member variable. 
Objects of this class are used in a multithreaded program. 
Would all the objects in this multithreaded program access the 

same static variable, or does each thread have its own copy! — 
Amit Wamburkar 


A‘ static class member variable is just like a C static global. 
There's just one instance, in the module where it’s defined. 
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class CSomeClass { 
public: 
static long g_nObjects; 
ie 
// the one-and-only 
long CSomeClass::g_n0bjects = 0); 


This is why in order to write thread-safe code, you have to pro- 
tect static members with a lock or use thread-safe functions like 
InterlockedIncrement and InterlockedDecrement. 


CSomeClass::CSomeClass() 
// increment object count 
InterlockedIncrement(&g_n0bjects); 

} 

If you want each thread to have its own copy of a variable, you 
can put the variable in an object that you pass as the startup para- 
meter (LPVOID) when you call your favorite begin-thread func- 
tion: AfxBeginThread, _beginthread, CreateThread, or whatever. 
You can then either pass the state object back and forth in all your 
thread functions, or, if that’s too cumbersome, define a thread- 
local variable. 

__declspec(thread) CThreadState foo; 


Now there’s one foo variable per thread. The Microsoft com- 
piler-specific “thread” at- 
tribute makes it easy to 
define thread-local storage 
using declspec, instead of 
allocating the storage 
through the thread local 
storage (TLS) API func- 
tions TlsAlloc, TlsFree, 
and so on. For more info 
about TLS, search the docs 
for “thread local storage” 
or. ELS. 


issues/0600/c/c0600.asp) where you describe loading an AVI re- 
source, this sequence loads a BY TE string resource: 
BYTE* IpRsrc = (BYTE*)LoadResource(hInst, hRsrc); ASSERT(1pRsrc); 


Q: your June 2000 column (http://msdn.microsoft.com/msdnmag/ 


Is it necessary to delete IpRsrc once youre finished with it? The 
Microsoft documentation for LoadResource is vague: “The sys- 
tem automatically deletes these resources when the process that 
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loaded them terminates, however, calling the appropriate function 
saves memory and decreases the size of the processs working set.” 
have not been able to successfully delete IpRsrc using any of the 
Delete or Destroy functions. 

Teya Nikov 


There’s never any need to free resources loaded with Load- 
Resource because LoadResource doesn't actually load any- 
thing. All LoadResource does is return a pointer to your resource 
in process address space, in the already loaded EXE or DLL. Noth- 
ing is allocated from the heap or anywhere else. If your program 
doesn't access the resource, its memory can be swapped out as per 
the normal Windows swapping algorithms. If your program ac- 
cesses it again, it'll be swapped in again. 
The documentation is definitely cryptic. It says that in the case 
of accelerators, bitmaps, cursors, icons, or menus, you can use the 
appropriate Destroy/Delete function to destroy the object: 


DestroyAcceleratorTable 
DeleteObject // for a bitmap 
DestroyCursor 

Destroylcon 

DestroyMenu 


But elsewhere the documentation says: 


It is only necessary to call Destroylcon for icons and cursors created 
with the CreatelconIndirect and the Copylcon functions. Do not use 
this function to destroy a shared icon. A shared icon is valid as long as 
the module from which it was loaded remains in memory. The follow- 
ing functions obtain a shared icon: LoadIcon, LoadImage (if you use 
the LR_SHARED flag), and CopyImage (if you use the LR_COPY- 
RETURNORG flag and the hImage parameter is a shared icon). 


For DestroyAccelerator table, the documentation says you can call 
this function whether the accelerator table was created with Create- 
Accelerator Table or LoadAccelerators. 

What should you make of all this mystification? The simple 
answer is that if the resource comes from your executable file (EXE 
or DLL), you don’t need to free it. If you call some function to 
create the resource, you do—and you should use one of the De- 
stroy/Delete functions just mentioned. Got it? 


Send questions and comments for Paul to cppqa@microsoft.com. 


of Windows++: Writing Reusable Windows Code in C++(Addison-Wesley, 1992). Paul can be 
reached at askpd@pobox.com or http://www.dilascia.com. 
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